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PREFACE 


The purpose of this manual is to explain in detail the internal 

workings and external interfaces of the system software of the 

unexpanded NewBrain A/AD. This software is implemented mainly in 

the 8K rom space located at addresses 56K-64K of the NewBrain Z80A 
processor. Additionally a brief description is given of the NewBrain 
BASIC dynamic compiler (implemented in the 8K rom space located at 48K-56K 
and the NewBrain mathematical package (implemented in 8K system software 
ROM space located at 56K-64K). 


Since the manual was first written a high resolution graphics device 
driver for the NewBrain has been produced and it is now supplied as 
standard in NewBrain A/AD models implemented in the 8K rom space 
located at 40K-48K. Other routines in this space modify the system 
software and a list of these modifications is given in Appendix C. 


Further details of the system software and information relating to 
modifications are contained in the NewBrain Technical Notes, which 
Should be appended to this manual. The external interfaces of the 
BASIC, the high-resolution graphics driver and the screen editor are 
defined in Technical Notes, but details of their internal workings, 
beyond the information given in this manual, the Handbook and the 
Technica! Notes, is not available to users. 


Expanded NewBrain Systems (i.e. those in which the NewBrain A/AD is 
connected to e.g. an Expansion Interface Module or a Disk Con- 
troller Module) make use of additional software including the New- 
Brain paged memory operating system. Software which makes use of 
internal features documented here and e!sewhere may not be compatible 
with expanded systems; furthermore the external interfaces of certain 
software may need to be amended in expanded systems. An outline of 
the rules to be followed to ensure compatibility is given in Appendix D. 


Users of this manual are warned that there may be inaccuracies. 


Grundy Business Systems Ltd 
Science Park 

Milton Road 

Cambridge 

UK 
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i INTRODUCTION 


This document describes the system software available on all Newbrain 
processors. There are three current models which offer particular hardware 
features: 


- Model M; ‘Page Register’, Expansion Port onto 280 bus, Video, 
ACIA/CTC, User Port. 


- Model A; Expansion Port, Video, no User Port but has software 
driver serial port - s/w Printer, s/w V24. 


- Model V; ACIA/CTC, User Port 


Models are suffixed with B and/or D indicating battery back-up and internal VF 
display respectively. 


1 SYSTEM SOFTWARE 


The system software including BASIC and Floating Point Maths Pack is common to 
all models though not all models can make use of ali the software. The overall 
control software module is called 05, Operating System, which gains control at 
power up and performs initial memory validation and initialisation. An own 
memory area is maintained in fixed memory locations O-FFH. Interrupt handling 
and other top level functions are performed by 05. These are provided by routines 
internal to 05, the entry points of which are available through a routine address 


table. 
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OS and 105 may be considered as permanently active tasks. Both support own 
memory areas constantly in use through User program request or directly by the 
User program. 05 supports the page zero (first 256 bytes) parameters and 105 
maintains a table of active devices, the Stream Table, and a device driver own 
memory area. The Random Access Memory organisation determined by 05 and 105 
is shown below: 


0000 
Params PARS = 256 
Fixed Memory for ҮРӨӨ леб 
Maths Pack 
а ац 
Stack Area | STKRAM = 200 
STACK/IOSRAM 
STRTAB Stream Table 
B3PRM/STRTOP 
User 
Program 


B4 
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The address STACK, the base of the stack, and IOSRAM which is the start address 
of Device Driver Own Memory are concurrent. Тһе Stack Pointer is initialised 
by 05 but may be changed to point into the User Program memory if a larger 
stack area is required. ВЗРАМ marks the base of the User Program and is 
normally concurrent with the top of the Stream Table. When 105 requires memory, 
at the time of a new Stream Table entry, then the User Program is requested by 
05 to provide the desired memory space. If the User Program can supply this 
memory B3PRM is temporarily set on the new base of the User Program area. When 
the table entry is subsequently made STRTOP becomes equal to B3PRM again. 


The Operating System links to the Input/Output System, 105 by means of ап intercept 
mechanism in OS. User programs which require IO operations make an appropriate 
Call through 05 which translates this to ап 105 request through а routine address 
table. 105 is itself a level of software above both the user program making 

the 1/0 request and the device driver modules actioning the request. 05 functions 
are available through the same mechanism. 


The implementation of a typical User Program 1/0 request is shown here graphically. 


05 
5732 
(OPENOUT 105: OPENOUT 
+ params“ pn W 
ү” 


ТР10: OPENOUT 
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BASIC, as an example of a User Program wants to open the cassette driver in 
preparation for a data output to tape. BASIC makes the request through the 
intecept routine іп 05, passing it the IOS routine request with parameters in 
the registers. The IOS routine is called and from the passed parameters 
determines the driver and its open routine. On completion of the open the 
driver passes control back to 105 which returns to the User Program. 16 is 
possible to call 105, the driver routine, or even directly drive an 1/0 
device from a User Program, but whether the user is implementing a new driver 
or his own User Program it is advisable, and indeed good software practice, to 
adopt the Newbrain standard interfaces. 
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1.2 USER PROGRAM 


The User Program becomes active when it is called by OS after initialisation. 

Its memory allocation is determined by the values of B3PRM which marks the base 
address and B4 which marks top of available RAM. 1% is expected that User 

Programs are designed such that all memory accessing is relative and that the 
memory boundary addresses need not be referred to after User Program initialisation. 
To this end, the IX and IY registers are maintained by all system software routines. 
On entry no devices are open but default devices have been set up by OS in the 

page zero params though these may be ignored. Three program modules are present 

in a User Program:- 


- The User Program itself providing the desired application 
function. 


- A Make Space module which performs the processing necessary 
when 05 makes a memory request from the User Program. 


- A Return Space module which performs the processing necessary 
when 0S returns memory to the User Program expanding the 
User Program space. 


The address of the memory space modules are set by the User Program into the page 
zero parameters. Although the system supplied User Program BASIC dynamically 
adjusts its internal base address,a fixed application User Program, the maximum 
10S requirements of which can be determined, can reserve sufficient space at its 
low memory addresses for any 05 memory requests. Іп this case the Make Space and 
Return Space routines become trivial. 
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1.3 DEVICE DRIVERS 


Supported through 105 are a number of code paths which perform 1/0 operations 
for the following devices:- 


- — Twin cassette tape driver 

- ТҰ and YF display drivers 

- Keyboard drivers 

- Software timed Line Printer driver 
- Software timed V24 driver. 


The device driver routines аге seldom active and only by User Program request. 
Typically, while any of these are process ing · other system operations are 

curtailed. Most notably the video display is disabled during data transfer to 
avoid data loss and to maintain synchronism for software timed serial data IO. 


Two display types are supported which may be driven individually or simultaneously. 
The Video structure supports 40 and 80 character per line and from 1 to 30 lines 
display lines. Various hardware options are supported. Тһе VF display is а 
single line 16 character unit mounted within the Newbrain processor. By default 
the internal software line length is 80 characters, the full line contents being 
viewed by scrolling left or right. Тһе device driver which interfaces to the 
display hardware is supported by a comprehensive display editor package. 
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1.4 HARDWARE 


The Newbrain processor is based on the 289 device supported by an intelligent 
10 microprocessor, the COP 420 GUW. Via a number of protocols the СОР 
communicates with the 780 passing data and control information in order to 
drive the following:- 


- — cassette 
- keyboard 
- VF display 


The COP maintains a status check on battery condition and whether the STOP 
keyboard key has been depressed. 


Оп battery models of the Newbrain the 280 may power down while waiting for a 
keyboard key to be depressed and can command the COP to power down at this time. 
Control circuitry and ROM modules associated with these devices are powered down 
with them. Four independent power circuits supply hardware elements within the 
Newbrain:- 


- VØ power is always present and supplies the random access 
memory and its control. 


- — Vl is the COP and related circuitry supply. 
- V2 is the 280 supply. 
- V3 supplies power hungry 10 devices such as video. 


The Newbrain only supports the Maskable Interrupt Mode 1, non-maskable interrupts 
are disabled by holding the NMI pin high. 
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Priority servicing is determined by software with the COP having the highest 
priority іп the 05 interrupt handler. The COP service routine does not enable 
interrupts and runs for a maximum of 600 microseconds. Interrupts are disabled 
during the serial transfer of a byte in the software timed drivers. The 
duration of the disable is dependent on baud rate. Mode 1 interrupts are 
vectored through location 38H equivalent to RST56. The other Restart locations 
are used as follows:- 


Restart Use 
RST8 Мау be used by апу routine which should redefine 


it if contro! passes to other users. Currently 
these are the tape driver and display driver. 


85716 Мау be used by the User Program {ог any purpose. 
RST24 Used by BASIC as intercept locations through 05. 
RST32 Intercept locations for 0S, Maths Pack and 

RSTAO 105. 

RST48 Reserved for use within interrupt handling software. 


Note RST8 should not be used within interrupt handler. 


The 280 performs 10 through hardware ports. Thirty-two ports are currently 
defined, port numbers of 32 and greater are reserved for future expansion. Two 
ports 7 and 20, the Enable and Status registers respectively are important in 
controlling the Newbrain operation and are frequently driven by operating software. 
Two formats of Enable register are defined:- 


* Model A has interface to software driven V24 devices 
* Other models with hardware driven V24. 
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Bits 7 and 6 of the Enable Register are also used to define one of four possible 
conditions of the Status register bit 9. Similarly bits 5 and 4 of the Enable 
Register select a signal for bit 1 of the Status Register. No conflict is 
generated by the dual use of bits 7 to 4 of the Enable register as they are 
validated in their V24 mode by signals at other ports. Ап OUT instruction to 
the Enable Register with the appropriate bits set results in the selection of 
data for bits 9 and | of the Status Register on subsequent IN instruction. The 
Structure of these registers are shown overleaf in Table 1.4. А full description 
of all ports is given in Appendix A. 
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Model A Enable Register 


Bit 9 = CTock Enable 

Bit 2 = ТҮ Enable 

Bit 4 = CTear Tor Sending 
Bit 6 = Not Used 


Not Model А Enable Register 


v24 
Selection 


Bit @ = Clock Enable 
Bit 2 = TV Enable 

Bit 4 = ves Sel.Rx.Bit 9 
Bit 6 = V24 Sel.Tx.Bit 0 
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Bit 1 = Not Used 

Bit 3 = Not Used 

Bit 5 = Transmit data V24 

Bit 7 = Transmit data Printer 
Bit 1 = User Enable 

Bit 3 = V24 Enable 

Bit 5 = V24 Sel.Rx. Bit 1 

Bit 7 = V24 Sel.Tx. Bit 1 


Rx 00 = Таре Loop 9, 01 = Tape Loop 1 
12 - Not Used, 11 = Serial Comms. 

Tx 0) = Tape Loop b, #1 = Tape Loop 1 
10 = Printer 11 = Serial Comms. 


Status Register 


Table 1.4 


n 19 
Bit Ø = CaTT Ind, tape in, 
Bit 1 = CaTT Ind, Bee, 
Bit 2 = Mains Present 
Bit 4 = User Interrupt 
Bit 6 = ACTA Interrupt 


n 
40/80, 


TV console, Power Up 
Bit 3 = User Status 


99 
Excess 


Enable Reg Bits 
7, 6 
5,4 


Bit 5 = Clock Interrupt 


Bit 7 = COP Interrupt 
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1.5 DOCUMENT STRUCTURE 


The other sections within the Newbrain Software Technical Description describe 
the Operating System, I0S and Standard Device Drivers, and gives a structural 
overview of BASIC and the Maths Pack. Certain routines within the operating 
software are particularly useful and the interface conditions to these are 
given in the following format :- 


Entry: Specifies the entry point of the routine 
and identifies those registers which have 
specific contents used by the routine. 


Function: A brief description of the operation performed 
by the routine. 


Routines: Where appropriate any major subroutines called 
are named with section numbers where they are 
described. 

Exit: The register contents on exit from the routine 


are described. Carry is clear for a normal exit, 
set to 1 if an error condition has been detected. 
IX and IY are always maintained and are not 
mentioned in the preserved register list. 


Params: Lists the page zero variables used by the routine. 
An asterisk alongside the routine indicates that the 
variable may be updated. 


Ports: Any ports written to or read by the routine are 
listed. 


1 
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2.1 INTRODUCTION 


The Newbrain Operating System, OS, is a collection of routines, some of specific 
functions and used internally and some more general and called by external 
programs. The power up and interrupt service routines are an example of the 
former and since the operation of reading a keyboard key is closely associated 
with the hardware and power-down this routine is also present. 


05 also contains fundamental routines called from external programs. Тһе 
intercept mechanisms allow users to call routines through the operating system 
via tables of addresses enabling specific calls to be re-routed if necessary. 
The Operating System is also the repository of other simple routines of general 
interest - syntax, memory management, power control, system queries and is the 
location of the standard device table. 
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2.2 POWER UP 


As power is applied to the processor the E ROM is decoded at each 8k page 

in the 280 address space. Thus the instruction at location 999p at this time 

is identical to that at E909 i.e. JP Ep93. This has the effect of loading the 
PC withEØØ3 from which address the next instruction is taken. This instruction 
sets the interrupt mode to 1. Тһе Enable Register port is written to with TV 
disabled and selecting EXCESS and PWRUP, bits Ø and 1 of the Status Register. 
The power up sequence loops until the PWRUP bit becomes set. 


2.2.1 Memory Test 


The power up procedure then enters the memory test sequence. The RAM test 
performs four write/read check loops writing four bit-patterns to each location 
and complementary bit patterns to adjacent locations, i.e. on first pass all 
zeroes and all ones are written to adjacent locations throughout RAM; оп second 
pass 55H and AAH are written to adjacent locations etc. 0п the read check phase 
the contents of each location are compared with the written value. Each location 
is checked until either top of RAM, hard coded as 9FFF, is reached or an error 

is detected. ІҒ an error then the top of RAM is set as the immediately previous 
memory address. 


At the end of the memory test the register pair DE contains either the address 
of top of RAM + 1, or if a memory error detected the last "good" odd (not 
divisible by two) memory address % 1. 
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2.2.2 System Parameters 


Following the memory test the default system parameters hard coded in the E999 
ROM are block moved down to the 9202 RAM. А list of parameters is given in 
Table 2.2 Тһе following default parameters are then immediately modified/ 
verified: 


1) 84, set to the highest "good" RAM address + 1. 


2) If the EXCESS bit of the status register is set, the 
EXCESS parameter is modified from its default value 
of 4 to 24, EXCESS is used by the video device and 
described in section 5. 


3) If the Mains Present bit is set and the TVCNSL and 40/80 
bits of the Status Register are zeroes, then the default 
parameter string length (DPSL) of 3 is not changed specifying 
an 80 character 24 line video device. Otherwise DPSL is set to 
9, which if the console is a video specifies a 40 character, 
24 line display. 


4) Тһе default console output device (Ee) number is set to 0 
which defines a video display as the console device. If the 
Mains Present bit is Q or the TVCNSL bit is reset then the 
DEV parameter is set to 3 specifying the VF display as the 
console output device. 


Initialisation complete, the start up sequence ends by testing whether an 
expansion ROM is fitted at location AQ9g. If so, its first byte is gH. 

If Bit 7 of the contents at A999 is zero, then OS jumps to agg. Otherwise, 
interrupts are enabled, the user address is retrieved from system parameter 
"UP and jumped into. 


16 
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Address 


00 
01 


44 


0% 


1C 


Table 2.2 


Length 


1 
3 


TPON 


B3PRM 


B4 


ТВ5Т8 


DEVO. 


EXCESS 
TVO 


түг 


T1 


TEXM 


DEV2 


5АУЕ2 


5АУЕЗ 


TEXMNC 


PLLEN 
PHPOS 


System Parameters 


Value 


Disable Interrupt instruction. 

Transfer for КТ, for wake-up after 

78) power down 

Lower bound of RAM allocation to user 
Program initially set concurrent with 
STACK top 

Upper bound + 1 of RAM allocated to 

user program 

Transfer for RST 8, used by maths 

and cassette dd 

Device driver number of default console, 
used by BASIC 

For TV device driver defaults to 4 

For ТҮ device driver - flash clock 
initially set to zero 

For ТҮ device driver - cursor flags 
initially set to zero 

For TV device driver - character at 
cursor initially set to zero 

Transfer for RST16, user program 
intercept "call by name" 

Nember of BASIC default store device, 
normally cassette 

IX save by 105(Ғог communication between [05 & 
IY save by 10S(user program) 

Transfer for RST24,user program intercept, 
"call no carry by name" 

Print line length for TAB and POS in BASIC 
Print head position for TAB and POS i. 
BASIC 
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Address engt Name Value 

10 ) PZLEN Print zone length for TAB and POS in 
BASIC 

JE 2 Saut! SP save for power down 

20 3 TRST32 Reserved for RST32 use by OS intercept, 
“call by name" 

?3 1 BRKBUF Used by BRKTST and other routines 


which detect break-in conditions 
(e.g. cassette driver) 


24 1 ENREGMAP Last byte sent to the enable port register 
25 1 ToPuC 1/0 power user count initially set to zero 
26 2 uP User program address defaults to BASIC 

28 3 185742 Reserved for RST49 use by 05 intercept, 
“call по carry by name" 

28 1 KBMODE Graphics and shift key lock status 
initially 9. 

2с 2 GSPR User program make space routine address 

2Е 2 RSPR User Program return space routine address 

30 3 1851748 Reserved for RST48 

33 1 BUFLG then set indicates buffers in motion, 
initially p. А Р 

34 2 OPSP Default parameter string pointer for 
device 9, initially points to string "124" 

36 2 DPSL Default parameter string length for device 
9, initially set to 3 

38 3 TINT Transfer for RST56(mode 1 device 
interrupt service) 

38 1 COPCTL COP control, interrupt acknowledge byte 
written to COP in response to a COP 
interrupt 

3c 1 COPST COP status, set by COP interrupt service 
routine 


Table 2.2 System Parameters 
cont. 
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Address 


30 
ЗЕ 


4p 


50 


52 


56 


58 


5А 
5С 
5E 
69 


62 


64 


66 


69 


60 


60 


Table 2.2 — System Parameters cont. 


Length 


1 
16 


mmm 


COPBUFF 
OUTBUFF 


TIMBUFF 
CHKSUM 


CLACK/CLOCK 
STRTAB 


DEVTAB 


TVCUR 
TVRAM 
OTHERI 
OTHER? 


TOSRAM 


STRTOP 
TNMI 
FICLKM 
TBRP 


RBRP 
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Value 


Data characters to COP 

VF display buffer initially 

set to spaces 

COP internal counter value used to 
time the 1 minute power down interval 
Tape transfer accumulated checksum, 
initially 0. 

Count of COP interrupts 

Address of start of stream table 
initially set concurrent with STACK 
top 

Address of start of device table 
initially points to hard coded table 
іп E000 ROM 


Address of cursor position 

Start address of TV own memory 

Reserved for use by driver which needs 

to maintain page zero memory address 
variable if own memory moves. 

Address of device driver own memory area 
for streams initially set concurrent with 
STACK top. 

Address of end of stream initially set 
concurrent with STACK top 

Transfer for NMI (not used, NMI pin 
strapped high) 

Frame interrupt counter, while video device 
is active ` 
Transmit baud rate parameter, default se.cing 
is 2 

Receive baud rate parameter, default 
setting is 2. 
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2.3 MEMORY MANAGEMENT 


Entry: SPACE, GSPCBK 
BC = number of bytes 


Function: Provides an interface with the user program 
get space and return space routines. 


Routines: SPACE 
GSPCBK 


Exit: Carry set if error detected (only for SPACE) 
А = error code 100 = no memory space available 
BCDE preserved 


Params: СРЕ 
RSPR 
B3PRM * 
SAVE? * 
SAVES * 


On entry to these routines BC contains the number of bytes required or to be 
returned. The user program routines are held in page zero locations GSPR and RSPR, 
get space and return space respectively. The user program index registers are 
saved in page zero location SAVE2 and SAVE3 and are restored prior to the CALL 
into the user space routine. 


On return the user program index registers are re-saved in SAVE? and SAVE3. The 
page zero location B3PRM, which contains the memory address which is the lower 
bound of user space, is updated either by adding BC to it in the event of a SPACE 
call, or subtracting BC bytes from it in the case of GSPCBK. 


20 
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The user program is supplied the number of bytes required or returned in BC. 
IX and IY are set on entry to the user program space routines as they were on 
previous exit from the user program. 1.е. 05 maintains the user program index 
registers. 


On return from the user program space routine BC DE are expected to have been 
preserved. The condition of IX and IY replaces the previously maintained user 
program index registers. I. e. next time the user program regains control IX and 
ТҮ are as modified by the user space routines. 


21 
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2.4 KEYBOARD 
Entry: ІММКЕҮ, GETKEY 


Function: Gets a byte of keyboard date from COP; IMMKEY returns 
immediately with or without data; GETKEY waits until 
à key depressed. 


Routines: IMMKEY 
GETKEY 


Exit: А = keyboard data byte, carry clear if valid, carry set 
if no data available, GETKEY never sets carry. All registers 
including alternates may be destroyed since 789 can power 
down while waiting for a key. 
1X and IY are still preserved. 


Params:  COPST * 
COPCTL * 
TIMBUFF * 


The GETKEY routine does not return to caller until a keyboard key has been depressed 
and a byte passed via the COP to the 780 — IMMKEY returns immediately to caller 
picking up a data byte if one is available. 


2.4.1 IMMKEY 


Interrupts are disabled and the KDATA Bit 6 of page zero location COPST (COP 
status) is tested and always reset. The contents of COPBUFF are written to the 
accumulator. Interrupts are then enabled. 


22 
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16 KDATA was set on entry indicating that COPBUFF contained a data byte then 
IMMKEY returns to caller with carry clear and accumulator containing data byte. 
Otherwise returns with carry set. BCDE are preserved. 


2.4.2 GETKEY 


The GETKEY routine only returns to caller once the COP has written a byte to 
COPBUFF and set KDATA, Bit 6 of page zero location COPST (COP Status). The 
IMMKEY routine is used to clear the COP interface. 


The index registers are saved and IMMKEY called. This has the effect of clearing 
the КОАТА bit - no data is associated with this call. The GETKEY routine then 
enters a wait loop. Interrupts are disabled and the KDATA bit tested If not 

set then the last written byte to the Enable Register is examined and if the 
IOPQUER Bit 3 is set, interrupts are enabled and the wait loop re-entered. If the 
IUPOWER Bit is zero the 280 enters a power down routine. If the READY Bit 5 

of COPST is not set or the TIMEOUT Bit 4 of COPST is set then interrupts are 
enabled and а HALT is executed powering down the 780. Otherwise the command 

B8 (updates timer, disables regular interrupts) is written to COPCTL and TIMBUFF 
is loaded with the 1 minute power down count prior to the EI and HALT instructions. 


Eventually a keyboard key will be depressed resulting in a power up or normal 
interrupt. The routine is forcedback into the wait loop where KDATA is tested 
and should be true. Having reset the TIMEOUT bit of COPST, the IMMKEY routine 
is performed prior to return to caller. The accumulator wili contain the data 
byte and carry will be clear. AFBCDEHL and alternate registers are destroyed if 
780 powers down. 
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2.5 INTERRUPT SERVICE 
Entry: INTRPT 
Function: Handles COP and Frame Interrupts 


Routines: ЕВІМТ section 2.5.2 
COPIS section 2.5.1 


Exit: AFBCDEHL preserved 
Two interrupt service routines are currently supported:- 


- Frame (Clock) Interrupt 
- СОР Interrupt 


Interrupts are defined on power-up to be mode | which force a restart through 
location 38H. This results in a jump to the location INTRPT. The Status 
Register is read immediately as some devices drop their interrupt lines quickly. 
AFBCDEHL are saved on the stack. The interrupt bits of the Status Register 

аге tested in the sequence COP, Clock. ІҒ an interrupt bit is set the specific 
interrupt handling routine is entered. 


On return, AFBCDEHL are popped off the stack, interrupts are enabled and normal 
program execution continues. 


230CT81-V0-CRS RS NEWBRAIN-TEQH-2.5 _ 02.00 
2.5.1 COP Interrupt Handling 
Entry: COPIS 


Function: Handles COP interrupts 


Routines: ^ REGINT section 2.5.1.1 
CASSERR section 2.5.1.2 
CASSIN section 2.5.1.3 
KBD section 2.5.1.4 
CASSOUT section 2.5.1.5 


Exit: Normally returns through one of routines branched to. 
Abnormally on unrecognised COP interrupt returns to caller 


Params: COPCTL 
Ports: СОР 


The СОР 1/0 port is read. Тһе contents of COPCTL (COP control), set previously 
by a routine requiring a specific COP service, are written to the COP 1/0 port 

both as an acknowledgement of the COP interrupt and as the issue of the next COP 
command. The top 4 bits of the COP input byte determines the type of interrupt. 


Value of Bits 4-7 Interrupt Type 


2 REGINT, Regular Interrupt occurs at approximately 
once every 12.5 mS 

CASSERR, Cassette error 

CASSIN, Casette input 

KBD, Keyboard 

CASSOUT, Cassette Output 


э ою ә 
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Each of these COP interrupt types has its own service routine. Any other value 
of bits 4-7 results in an immediate return out of the COP interrupt handler. 


2.5.1.1 ВЕСІКТ 


Entry: REGINT 
А = COP input byte 
C = COP port number 
D = COP acknowledgement/command byte 
HL points at COPST 


Function: Тһе operations to support the previous issued command byte are 
performed plus general Regular Interrupt housekeeping 


Exit: No special conditions, normal return, though abnormally can jump 
to power off instruction 


Params: cops 
COPCTL * 
CLACK * 

Ports: Status Register 
COP. 


The bits 0-2 of the COP input byte are or'd into the corresponding bits of 
COPST (COP Status). Тһе READY bit 5 of COPST is set. Ву default the next COP 
command is set to NULLCOM(D9H) and this is written to COPCTL. Several of the 
output commands sent to the COP on entry to the COP Interrupt Handler, 2.5.1, 
require additional operations. 


1f the command was DISPCOM or TIMCOM, then a synchronous data transfer to the 
TOP is performed. Synchronisation is achieved when both COP and Clock interrupt 
states bits occur simultaneously (though a Clock interrupt need not occur). 
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At this time the data transfer begins,at a 1 byte per 20 microsecond rate. For 
DISPCOM 18 bytes are transferred. The first 2 bytes are "don't care", the 
remaining 16 are the contents of OUTBUFF. ТІМСОМ is supported by the transfer 
of 6 bytes. Only the middle 2 bytes are meaningful and are the contents of 
TIMBUFF . 


If the previous command was NULLCOM then the routine determines whether a full 
power down can be initiated. If both the TIMER® Bit 9 of COPST (determined by 
COP input byte) and the TIMEOUT Bit 4 of COPST are set then the PONCOM is 
written to the COP port. The timeout bits of COPST are cleared and DISPCOM 
is set in COPCTL so that on power up the VF display is refreshed from 

OUTBUFF. The routine then jumps through TOS to the POFF (Power Off) location 
which executes a HALT. 


Except when a full power down is initiated the REGINT routine ends by incrementing 
the Regular Interrupt count held in quadruple precision in CLACK. 


2.5.1.2 CASSERR 


Entry: CASSERR 
Registers as for REGINT 


Function: Sets READY and CERR Bits 5 and 4 of COPST and sets Error Code 130, 
Tape Drop Out, in COPBUFF 


Exit: No special conditions 


params: COPST * 
COPBUFF* 
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2.5.1.3 CASSIN 


Entry: CASSIN 
Registers as for REGINT 


Function: Reads a byte of data from the COP, if one is present; 
else tests whether the stop key has been depressed 


Exit: No Special Conditions 
Params: cops: 

COPBUFF * 

BRKBUF 
Ports: Enable Register 

coP 


Тһе lsb of the COP input byte is the Run-in bit indicating, when set, that no 
data is associated with this interrupt. If bit 9 of COP input byte is set, 

then bit 1 is tested and if set indicates the break key has been depressed. If 
break-in is allowed i.e. BRKBUF is zero then BRKOK, READY and CERR Bits 3, 5 and 
4 of СОР5Т are set and COPBUFF is set to zero. 


If bit Q of the COP input byte is zero then the COP will set a data byte at 
the COP port 290 microseconds after the COP interrupt which will remain until 
530 microseconds after the COP interrupt. А software countdown is executed and 
the COP port read. The retrieved data is set in COPBUFF. Meanwhile the Enable 
Register is written to resetting TVENA so that the video does not make a bus 
request during the COP data transfer with the possibility of losing the data. 
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2.5.1.4 кр 
Entry: KBD 


Registers as for REGINT 


Function: Reads а data byte from the COP 


Exit: No Special conditions 
Params: CoPsT * 

COPCTL 

COPBUFF* 
Ports: сор 


For а Keyboard Interrupt а data byte becomes valid at the COP port 290 
microseconds after the COP interrupt. KBD detects the data byte, not by 

timing 290 microseconds, since video is not disabled, but writing a byte to the 
COP port and waiting for it to change. 


The data byte output by the COP is the coordinates of the depressed key of 

the keyboard. KBD writes 80H to the COP port, which is not a valid coordinate, 
and enters a wait loop which includes a read of the COP port. When the data 
read is not equal to 80H, the wait loop is exited, the port is read again in 
case the data was in transition previously. Тһе КОАТА Bit 6 of COPST is set 
and the COP input data byte is written to COPBUFF. If the BRKOK Bit 3 of 
COPST is set, then if the data byte refers to the "*" key, both KDATA and 
BRKOK are reset prior to return. Ғоғ hardware reasons on certain machines 

the "*" key performs the stop key function during cassette searching. 
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2.5.1.5 CASSOUT 


Entry: CASSQUT 
Registers as for REGINT 


Function: Writes a byte of data to the COP 


Exit: No Special Conditions 
Params: copst * 

COPBUFF 
Ports: СОР 


Enable Register 


TVENA is reset by writing to the Enable Register. READY is set in COPST. The 
data byte held in COPBUFF must be written to the COP between 290 and 530 
microseconds of the COP interrupt. The interval is timed by a software countdown 
and the byte written. 
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2.5.2 Clock Interrupt Handling 
Entry: FRINT 


Function: Handles Clock interrupts 
Exit: Normal return to caller 


Params: FICLKM * 
BUFLG 


wwe » 
TVCUR 


Ports: Clear Clock Interrupt, port 4 
Load TV Addresses, Ports 8 and 9 
Enable Register 


The Clock Interrupt is cleared by executing an OUT instruction to port 4. The 
Frame Interrupt counter, FICLKM, in Page Zero is incremented. This is a triple 
precision count which, provided clock interrupts are enabled, gives an accurate 
20mS clock count. 


BUFLG is tested. This is set by 105 durina execution of a CLOSE when stream 
tables and own memory are being moved, see section 3. If BUFLG is set then the 
TV Enable Bit 2 of the Enable Register is reset effectively blanking the video. 
Normally BUFLG is zero so interrupt handler continues with cursor handling. 

The active locations in page zero are:- 
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ТҮЙ, contains the cursor flash clock 
TVI, contains the display character at the cursor position 
TV2, contains cursor status bits 


Bit Value 
0-3 Unused 
4 1 = Blank Video (For this frame only) 
5 g = Cursor is blob character 
1 = Cursor is underline 
6 1 = Cursor displayed 
9 = Cursor not displayed 


7 # = Blank Video 


TVCUR, 2 bytes, containing the RAM address within the TV store 
which is the cursor position address 


The flash clock, ТҮЙ, is incremented. 8145 4 and 7 are tested and if necessary 
TV Enable is reset. Bit 4 of TV2 is always reset by this routine. 


lf a cursor is to be displayed, Bit 6 of TV2 set, then the flash clock in 

TVØ is interrogated. Each 16 counts of ТҮ) causes the cursor to be alternately 
displayed and not displayed. Since the Clock Interrupt occurs once every 20mS 
this gives a cursor flash cycle time of 64015. If Bit 4 of ТУ) is set then the 
cursor, blob or underline (determined by Bit 5 of TV2), is set at the cursor 
address held in ТҮСІН. (Cunningly if the character at the cursor position is 
the cursor character, then during the cursor display phase of the flash cycle 
a space is written at the TVCUR address). If Bit 4 of ТУ) is zero then the 
character at cursor position held in TV] is written to the TVCUR address. 


Interrupts are enabled and the SETFRM routine, see section 6, is called. This 
places the start address of TV RAM store into BC. This address can be considered 
as: 
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lsb of address 


msb of address | 7 


The TV store start address always occurs оп a 64 byte boundary and іп the 
address range 0-32k and can therefore be specified in 9 bits. The most 
significant bits of the address are written to port 9. If Bit 6 of C is 

set then an OUT to port 8 15 executed. The OUT operation to port 8 causes 

the Bit 6 of the TV RAM address to be set. For output devices with an excess 
of 24, the Video Bit 2 of the Enable Register is set, the Enable Register 
written and the routine exits. Other devices expect a further OUT instruction 
to be executed. This does not write to a specific port but outputs the full 

16 bit address of the start of TVRAM store onto the address bus. Video is then 
enabled as before. 
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2.6 INTERCEPT MECHANISMS 


Entry: via RST16, RST24, RST32, RST40 
TOS points to an entry in ZOSTABLE or ZTABLE 


Function: Routes calls via a table of routine addresses. 
Routines: CALLOS 
COSNC 
CALLRTN 
CALLNC 
Exit: Jumps into required routine address 
TOS points to originator of RSInn return address 
AFBCDEHL preserved, 
The operating system provides a simple table based calling mechanism which makes 
use of the RST instructions of the 280. Forcing subroutine calls through the 
standard intercept code gives a number of benefits:- 
- solves the global symbol problem between ROMS 
- allows the easy addition of routines 
- maintenance 
Two tables of dobal symbols support the intercept code:- 


- TABLE contains the user program (BASIC) routine addresses 


- ZOSTABLE contains operating system and maths pack routine 
addresses 
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The tables define two byte entries of the form:- 


RSTnn 
Offset sword offset of routine address in ZTABLE/ZOSTABLE 


which are linked into the callers code. The operating system uses RST32 and 
RSTA which cause a jump to CALLOS and COSNC respectively. The user program 
uses RSTI6 and А5724 which cause a jump to CALLRTN and CALLNC respectively. 

Both sets of restarts behave identically except for operating through their 

own tables. 


2.6.1 CALLOS 


The registers AFBCDEHL are exchanged with the alternate register set. After 
the execution of the RST32 the re turn address“ pushed onto the stack is actually 
the address of the offset to the routine address in ZOSTABLE. The real return 
address is set on the stack by incrementing the address at the stack pointer. 

The byte address of the routine address in ZOSTABLE is calculated to be 


ZOSTABLE + 2* Offset where ZOSTABLE is the base address of 
the table. 


The contents at this address is the start address of the required routine. The 
routine start address is pushed onto the stack, the registers are restored and 
а RET instruction is performed causing a jump into the routine. 


2.6.2 COSNC 


This executes as CALLOS but only if carry is not set. If carry is set the correct 
return address is set on the stack and the routine returns to caller. 
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2.7 SYSTEM QUERIES 


There are two system query routines currently implemented. BRKTST tests and 
clears the break key flag; STKTST checks how much space is left on the stack 


LA 751 BRKTST 
entry: BRKTST 
Function: Tests and clears the break key flag 


Exit: If flag set А=0 carry is set 
Else carry clear 
BCDEHL preserved 


Params: — BRKBUF 
copst * 


The Page Zero location BRKBUF is examined. If non-zero then routine makes 
immediate return to caller with carry clear. If BRKBUF is zero then the 
BRKKEY Bit 2 of COPST (COP Status) is tested and reset, If set then A is set 
to zero and carry is set. If BRKKEY is zero then A contains BRKBUF contents 
and carry is clear. Preserves BCDEHL. 


2.7.2 SKTST 


Entry: STKTST 
BC = number of bytes 


Function: Determines whether BC bytes will fit in the remaining 
stack space. 


Exit: carry set if insufficient stack space BCDE preserved 
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2.8 DEVICE TABLE 


The address of the device table is found in the Page Zero location DEVTAB. The 
offset zero of the device table is the count of number of entries in the table. 
The devices supported are 


Of“ et Device 


9 11 = number of device table entries 

b TVIO Video console output 

3 ТР110 First cassette unit 

5 TP210 Second " к 

7 1110 VF display 

9 TLIO Combined Video and VF display 

n KBWIO Keyboard wait for a key 

13 К8110 Keyboard immediate return with a key 
if available 


19 UPIO User port 

17 LPIO Line printer 

19 2010 Software driven V24 

21 DUMMY Does nothing, may be used for 


directing discardable output 


Further details of device drivers may be found in section 3. 
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2.9 V3 CONTROL 


Each time а device is opened which uses V3 Power the routine IOPON is called. 
Similarly each time a device is closed which uses V3 Power the routine IOPOFF 
is called. Both routines maintain a count in IOPUC which is incremented each 
time IOPON is called and decremented each time IOPOFF is called. 


2.9.1 10PON 
Entry: — I0PON 


Function: Increments 10 Power Use Count and conditionally 
enables 10 Power 


Exit: No special conditions 
BCDEHL preserved 
Params: ENREGMAP * 
TOPUC Ж 


Ports: Enable Register 


Interrupts are disabled. The last byte written to the Enable Register is held 
at ENREGMAP. The IOPOWER Bit 3 of this byte is set and the new contents of 
ENREGMAP written to the Enable Register. Interrupts are then enabled. The 
ТОРЫС (IO Power Use Count) is incremented. If prior to being incremented the 
IOPUC was zero then ACINIT is called which initialises the АСТА and СТС. 
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2.9.2 10POFF 
Entry: 1ОРОРЕ 


Function: Decrements I0 Power Use Count and conditionally 
disables 10 Power 


Exit: No special conditions 
BCDE and Carry preserved. 


Params: ENREGMAP * 
TOPUC * 


Ports: Enable Register 
TOPUC is decremented. If as a result IOPUC becomes zero then the IOPOWER bit 


of ENREGMAP is reset and the new contents of ENREGMAP written to the Enable 
Register switching off V3 Power. 
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2.10 SYNTAX 


Four useful routines are available for character and numeric string 
manipulation:- 


- lower to upper case conversion 
- numeric character to binary 

- numeric string to 16 bit binary 
- mumeric string to 8 bit binary 


2.10.1 Lower to Upper Case Conversion 
Entry: HLTTCAPS 
HL contains address of character for conversion 
or 
TTCAPS 
А = character for conversion 


Function: If the character is one of the twenty-six lower case letters 
then it is converted to its upper case equivalent. 


Exit: А = converted character 
Carry is set if the input character has an ASCII value less 
than 61H 
BCDEHL preserved 
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2.10.2 Convert ASCII numeric character to binary 


Entry: RDIGIT 
А = numeric character 


Function: If the character in the accumulator is one of the ten numeric 
ASCII characters, it is converted to its binary equivalent. 


Exit: А = binary number, Carry is clear 
Else A = input character, Carry is set indicating that the 
input character was not an ASCII numeric. 
BCOEHL preserved 


2.10.3 Convert ASCII numeric character string to 16 bit integer 


Entry: RDINT 
С = a string character count 
HL points to first numeric character held in memory; the 
character in the lowest memory address is the most significant 
digit. 


Function: Converts ап ASCII numeric character string or sub-string to a 
Sixteen bit integer. 

Exit: count on entry less number of numeric characters read. 

DE- binary integer 

HL contains address following the address of last numeric 

character read. 

Carry clear if no errors 


Carry set if overflow or first character read was non numeric 
B preserved. 


41 


230C181-VO-CRS NEWBRAIN-TECH-2.10 03.90 


This routine is specifically designed for converting numeric ASCII sub-strings 
from within 1/0 parameter strings. The entry parameter С is the total count 
of characters yet to be processed in the string and not the number of numeric 
characters for conversion. This parameter is maintained by the routine, 
decremented for each character processed, but if it becomes zerothe routine is 
exited. 


The routine processes character by character until a non-numeric ASCII value 
is detected. If this is the first character then an error is returned - carry 
is set. To ensure successful conversion it is imperative that the numeric 
string has a trailing delimiter so that the routine stops converting. 


2.10.4 Со! 


rt ASCII numeric character string to 8 bit integer 


Entry: ROBY TE 
Registers as for RDINT 2.10.3 


Function: Converts an ASCII numeric character string or sub-string 
into an 8 bit integer 


Routines: КОІМТ section 2.10.3 


Exit: С = count on entry less number of numeric characters read 
А = binary integer 
HL contains address following the address of last numeric 
character read 
Carry clear if no errors 
Carry set if overflow or first character read non-numeric 
BDE preserved 


Calls the RDINT routine having saved DE. Checks if the converted numeric string 
is greater than 255 and returns. 
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3.1 INTRODUCTION 


The NewBrain processors are provided with device driver programs which make device 
interfaces appear identical - all devices appear to be single byte serial. To 
further simplify the 1/0 interface a common set of calling routines, 105, is 
provided to enter device drivers. Using these routines all communication with 
device drivers is via data streams (sometimes known as channels, logica] devices 
оғ logical units). Routines are provided to initialise a device driver, assign 
it a data stream, allocate own memory to it, communicate with it and close it 
down. 


The existence of a device driver is made known to 105 by the presence of its 
entry address in the device table. The device table is pointed to by the 
contents of OS fixed location DEVTAB, see section 2.8. Each device driver 
may consist of any number of routines but typically supports five:- 


- OPENIN, 
- OPNOUT, 
- INPUT, 
- OUTPUT, 
- CLOSE 


The interfaces to OPENIN and OPNOUT are identical - a physicalport number and 
logical parameter string are passed to the routine, which is expected to 

initialise the device. When called via IOS the open routine may call MKBUFF 

in order to create own memory space. Open routines are expected to return a 
parameter string. The interface to INPUT, OUTPUT and CLOSE is simpler - one 

byte and a parameter, the port number is passed to the routine and one byte is 
returned. The port number is a parameter which has meaning only for the driver, and 
can select particular driver characteristics. For all drivers currently implemented 
this parameter is not used or is expected to be zero. 
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А device driver entry address is the first location of the routine table which 
is a list of one byte displacements to its routines. The first entry in the 
table defines the total number of routine entries and corresponds to a maximum 
request code that may be passed from 10S. A typical routine table may be 
defined as follows. 


DDRIV:  DEFB 4 device driver entry, max request code = 4 
DEFB DOPNIN-s у displacement to OPENIN, request code 9 
DEFB DOPNOU-S 3 displacement to OPNOUT, request code 1 
DEFB DINP-$ 5 displacement to INPUT, request code 2 
DEF8 DOUT-$ 3 displacement to OUTPUT, request code 3 
DEFB OCLS-$ 3 displacement to CLOSE, request code 4 


A set of six routines is provided to handle ali communication between the user 
program (e.g. BASIC) and Newbrain devices. These routines: OPENIN, OPNOUT, 
INPUT, OUTPUT, MOVE and CLOSE first identify the device driver to be used 

and then call the appropriate routine from the device driver. OPENIN and 
OPNOUT allocate а stream to the device, subsequent calls to INPUT, OUTPUT 

and CLOSE then reference the stream rather than the driver number and port 
number. As mentioned above device driver open routines may call MKBUFF to 
allocate own memory to a device, the address of this memory is passed to the 
device driver on calls to INPUT, OUTPUT and CLOSE. Оп return from a device 
driver CLOSE routine the stream and the own memory are deallocated by 105. 

А recommendation is made that own memory should not contain absolute addresses. 
This is because CLOSEing one device may cause the own memory for another device 
to be moved. Some devices e.g. TY require to make adjustments to the contents 
of own memory should it be moved. For these the sixth routine MOVE request 
code 5 is implemented. 
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The random access memory organisation is shown іп the following diagram:- 


0500 
system system 
space | variables 
“Boundaries may move when 
OPENing and CLOSEing 
losmaM device Drivers Suv: 
Own Memory 
* STRTAB 
ы STRTOP. 


When а stream is allocated by 105 open, the stream table entry is added at 
(STRTOP). When own memory is allocated by MKBUFF it is added at (STRTAB) 

and the stream table is shifted up. The own memory entry in a stream table 
entry is set to zero initially and if а driver requires no own memory it should 
be left at zero. The own memory address may be set by the device driver to 
point outside the IOS data structure - if this is done it is the user's responsi- 
bility, though generally has по ill consequences for 105. When streams and own 
memory are removed by CLOSE the IOS data structure is closed up. 
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When any of these memory adjustments take place all the 105 pointers and the 
own memory addresses in the stream table entries are adjusted to remain 
correct. 


A stream table entry has the structure shown below:- 
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3.2 OPEN 


Entry: OPENIN 
OPNOUT 
A = driver number 
D = port number 
Е = stream number 
BC = parameter stream length 
HL points to start of parameter string 


Function: Validates that no Stream Table entry is defined for input 
parameters, creates an entry and calls the driver OPEN 
routine, 


Routines: РОЕМ section 3.8 
FSTRM section 3.7 
SPACE section 2.2 
FDE section 3.6 


Exit: Carry clear 
BC, HL = parameter string returned from device driver 
Carry set 
A = error code from OPEN or device driver 
OPEN error codes are 107, Device/Port Pair Already Open 
108, Stream Already Open 
100, No Space For Stream Table Entry 
DE preserved 


Params: PLLEN * 
PHPOS * 
PZLEN * 
STRTOP * 
SAVE2 * 
SAVE3 * 


48 


O9NOV81-VO-CRS NEWBRAIN-TECH-3.2 02.00 


The open code executed, via the two entry points OPENIN and OPNOUT, differs 
only in that OPNOUT sets the carry flag on entry and OPENIN clears the carry 
flag. After the state of carry is fixed, the registers are pushed onto the 
stack and the index registers saved in SAVE2 and SAVE3 of page zero by calling 
the OS routine SAVIRS. If the stream number is zero indicating the console 
device is being opened the BASIC print formatting locations, PLLEN, PHPOS, 
PZLEN are zeroised. 


FDEV, section 3.8, is called which checks that no entry for the specified driver 
and port exists іп the Stream Table. ІҒ it does then А is set to error code 
107, Device/Port Already Open, and with carry set OPEN retums. If no entry 
exists, the FSTRM is called which checks that no entry for the specified 

stream exists in the Stream Table. If it does then it is set to error code 108, 
Stream Already Open, and with carry set returns to caller. 


Once OPEN has determined that no Stream Table entry exists, BC is set to 6 

and the routine SPACE, section 2.3, is called which obtains 6 bytes from the 
user program space. If insufficient memory exists then SPACE returns error 
code 100 with carry set and this is passed on to user by returning immediately. 


STRTOP now points to offset @ of the new Stream Table entry. Тһе stream number, 
driver number and part number are written to the table entry, offsets 3,4,5 
are zeroised. Тһе new value of STRIOP, 014 value + 6, is set in page zero. 


The state of the carry flag as set on entry through OPENIN or OPNOUT is used 
to determine the device driver request code. For IN this is 9, for OUT, 1. 
FOE, section 3.6, is called which loads HL with the OPENIN or OPNOUT routine 
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start address for the specified driver. This is swapped with the parameter 
string start address so that on entry to the driver OPEN routine:- 


D = port number 
Е = stream number 

8C = parameter string length 

HL = parameter string start address 


lf an error was detected by FDE then the 105 OPEN routine returns with A 
containing the FDE error code without calling the driver OPEN. 


On return from the driver, the index registers are restored by calling RESIRS 
which extract IX, IY from the temporaries SAVE2, SAVE3. If the driver OPEN 
routine detects an error, it will set carry and return an error code in the 
Accumulator. REMOVE, section 3.4, is called which in this case removes the 
Stream Table entry and any own memory defined by this call to 105 OPEN. 


09М0У81 - V0- CI 


3.3 


Entry: 


Function: Sets the request code in the C register and calls IOC:- 


Routines: 


Exit: 


RS 


INPUT /OUTPUT /MOVE 


INPUT 

OUTPUT 

MOVE 

А = data byte if OUTPUT 
Е = stream number 


INPUT , C= 2 
OUTPUT, C = 3 
MOVE ,C=5 


10С section 3.5 


Carry clear 
А = data byte if INPUT 
Carry set 

A = driver error code 
BCOEHL preserved 
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3.4 CLOSE 


Entry: — CLOSE 
E = stream number 


Function: Sets the close request, 4, in the C register and calls the 
device close routine. On return removes the Stream Table 
entry and any own memory. 


Routines: loc section 3.5 
FSTRM section 3.7 
GSPCBK section 2.2 


Exit: Carry may be set by device driver CLOSE routine and if this 
is error 
А = 105, carry is cleared 
BCDEHL preserved 


Params: 5АУЕ2 * 
SAVES = 
BUFLG 
STRTAB* 
STRTOP* 
IOSRAM 
TVCUR * 
TVRAM * 
OTHERI* 
OTHER2* 
DEVTAB 
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Тһе index registers аге saved in page zero via а call to SAVIRS. With the 
request code in С set to 4, 10С section 3.5, is called. If the driver 
returns with error code 105, No Stream Table Entry, the CLOSE routine 
returns immediately but with carry not set - error 105 is not an error 
for CLOSE. 


For normal or any other abnormal return from 10С, the routine REMOVE is 
executed. This removes the Stream Table entry of the closed stream and, 
should there be any, the own memory for the stream. The registers AFBCOEHL 
are all preserved оп the stack and bit @ of BUFLG is set indicating that 
own memory buffers and Stream Table entries are in motion (or about to be). 
FSTRM is called which returns the entry within the Stream Table of the 
stream to be closed. CHKPBD checks that the own memory address in the entry 
is greater than or equal to IOSRAM and less than STRTOP. 14 not then 105 
assumes no own memory and bypasses the own memory removal and pointer update 
code. 
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For an entry with own memory, the Stream Table entries higher in memory 
are accessed until one is found with an own memory address. Since the 
Stream Table entries and own memory are added in the same sequence, the 
next valid own memory address found in the Stream Table defines the 

upper bound of closing stream own memory. Тһе difference between the 

start address of the closing stream own memory and the next own memory 

is the number of bytes to block move the remaining device drivers own memory 
and Stream Table entries below the closing entry. 


TOSRAM 


Start of next 
own memory 


Start of 

Closing Stream 

own memory Real 
STRTAB 


Start of next End of previous 


STRTAB 


Closing Stream 
к ZL rable Entry 
Stream table 
entries not yet 
moved 


STRTOP 


Before After 


stream table entry 


56 


09NOV81-VO-CRS NEWBRAIN-TECH-3.4 04.00 


REMOVE then updates the following pointers by subtracting the number of own 
memory bytes removed:- 


- STRTAB 
- TVCUR 
- ТҰРАМ 
- OTHER] 
- OTHER? 


(N.B. DEVTAB is inspected but only updated if it lies between IOSRAM and STRTOP. 
Should additional device drivers be added to the device table, currently in 
ROM, it could be moved to the 105 area between own memory and stream table 
entries). 


The closing Stream Table entry is then removed by shifting down the higher 
address entries. STRTOP is adjusted by subtracting the bytes removed from 
device driver own memory and the Stream Table entry length, 6. This total 
bytes removed is given back to the user program via a call to GSPCBK. Starting 
with the first Stream Table entry, and accessing each entry in turn, MOVE, 
section 3.3, is called with HL pointing at entry start address. Returning 
error conditions are ignored. Once all have been processed BUFLG is cleared, 
the registers are popped off the stack, IX and IY are restored from SAVE2 and 
SAVE3, and the routine exits returning to 10S caller. 
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3.5 COMMON ROUTINE FOR INPUT, OUTPUT and CLOSE 


Entry: loc 
A = data byte if called by OUTPUT 
С = request code 
Е = stream number 


Function: Recovers parameters from Stream Table entry and calls requested 
driver routine passing Stream Table parameters in registers. 


Routines: FSTRM section 3.7 
FOE section 3.6 


Exit: Carry clear 
А = data byte if called by INPUT 
Carry set 
A = error code set either by 10С or by called drive routine 
10С codes are 105, Stream (specified in E) Not Open. 
DEHL preserved 


The registers DE and HL are preserved on the stack. FSTRM, section 3.7, is 
called which finds the stream table entry matching E. If this returns with 
carry set then the accumulator is loaded with the error code 105, Stream Not 
Open, and returns to caller. On normal return from FSTRM, HL points to offset 
zero of the required Stream Table entry. This is incremented to retrieve the 
driver number into B and again to retrieve the port number into D. Offsets 

4 and 5 are the own memory address for the stream and this is set in HL and 
pushed onto the stack. FDE, section 3.6, is called which returns with HL 
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pointing at the required routine entry address. This is swapped with the 
own memory address at TOS so that оп entry to the driver routine:- 


А = data byte, if called by OUTPUT 
D = port number 

E = stream number 

HL points to start of own memory 


lf an error was detected by FDE then routine returns with A containing the FDE 
error code and without calling the driver routine. 
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3.6 FIND DRIVER ENTRY ADDRESS 
Entry: FOE 


В = driver number 
С = request code 


Function: Computes the start address of the routine for request code 
С of driver number В. 


Exit: Carry clear, 
HL = entry address. 
Carry set, 
А = 106, Invalid Device or 109, Illegal Request code. 
DE preserved. 


Params: DEVTAB 


HL is set with the contents of page zero location DEVTAB which is the address 
of the Device Table. Offset zero of the Device Table is the number of devices 
in the table and this is compared with the driver number in 8. If B is greater 
than the number of devices in the table the routine returns with error code 106, 
Invalid Device, in the Accumulator. 


Since the entries in the Device Table are two bytes long the driver entry 
address is defined by:- 


HL + 1 + 2*8 since on entry HL is at offset 0 of the Device 
Table and the first device address starts at 
offset 1. 
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The two bytes starting at this computed address are set in HL which now points 
to the device driver entry address which is the routine table. 


Offset Ø of the routine table is a number which is the maximum request code 

for the driver. This is compared with the request code in C and if C is greater 
then A is loaded with error code 109, 111еда1 Request Code, and routine returns 
to caller. Otherwise the request code is added into HL + 1 to position HL at 
the requested routine table entry. The value at this entry, which is the offset 
to the routine start location, is added into HL. If this value is zero, then 
the driver does not support this request code and routine returns with carry 
set and error 109. Otherwise the computed driver routine start address is 
returned in HL with carry clear. 
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3.7 FIND А MATCHING STREAM NUMBER 


Entry: — FSTRM 
E = stream number 


Function: Attempts to find an entry in the stream table to match the 
stream number in Е. 


Exit: Carry is clear, indicating а matching stream table entry is 
found, and HL points to offset 9 of a stream table entry- 


Carry is set, indicating no stream table entry found, and 
HL points one past the last stream table entry (STRTOP). 
ABCDE preserved 


Params: STRTAB 
STRTOP 


The routine initialises the registers:- 


BC, AF, DE are pushed onto the stack 

- the stream number is set in the accumulator 
HL is loaded with the contents of STRTAB which 
points to the first entry in the stream table 
DE is loaded with the contents of STRTOP which 
points to the location one past the last entry 
in the stream table. 

BC is loaded with 6, the stream table entry 
length. 


D 


FSTRM then enters a loop which accesses each stream table entry and compares 
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the value in offset Ø of the entry with the stream number in the accumulator. 
For each iteration of the loop HL is incremented by BC until HL equals DE 
indicating the end of the stream table. If a match is found the carry flag 
is ‘reset and HL is left pointing at the offset P of the matching stream table 
entry. If no match is found HL will be equal to DE itself equal to STRTOP. 
The registers are restored and routine returns. 
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3.8 FIND MATCHING DRIVER/PORT PAIR 
Entry:  FDEV 
A = driver number 
D = port number 
Function: Attempts to find a stream table entry which has a driver 
number and port number which matches A and 0. 
Exit: As for FSTRM, section 3.6 
Params: STRTAB 
STRTOP 


The routine 


FDEV enters 


pointing at 
equal to DE, 


initialises the registers:- 


BC, AF, DE are pushed onto the stack 

HL is loaded with the contents of STRTAB which points 
to the first entry in the stream table 

- DE is loaded with the contents of STRTOP which points 
to the location one past the last entry in the stream 
table 

BC is loaded with 6, the stream table entry length. 


a loop which accesses each stream table entry and compares the 
driver number offset 1 of the table entry with the value in the Accumulator. 
1f unequal, HL is incremented by BC to get the next entry address and the 
result compared with DE to determine whether all entries nave been accessed. 
If a match is found, HL is incremented to point to the port number, offset 
2 in the stream table entry. This value is compared with the required 
port number in D and if these agree the routine exits with carry clear and HL 


offset Ø of the matching stream table entry. If HL becomes 
the routine exits with carry set indicating no match found. 
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3.9 MKBUFF 


Entry: — MKBUFF 
BC - number of bytes required 
E = stream number 


Function: Creates an own memory area of BC bytes. 


Routines: FSTRM section 3.7 
SPACE section 2.2 


Exit: Carry clear, 
HL points to start of own memory. 
Carry set if insufficient memory, 
А = 100 returned by SPACE, 
BCDE preserved. 


Params: —STRTAB 
STRTOP 


SPACE is called which requests BC bytes from the user program. If there is 
insufficient memory, SPACE returns with carry set and A = 100. MKBUFF 
immediately returns to caller. 1Ғ sufficient space, FSTRM is called to set 
HL pointing at the Stream Table entry specified by the contents of E. The 
offsets 4 and 5 are set to the contents of STRTAB which is the own memory 
address. STRIAB and STRTOP are adjusted by adding in the own memory size 
and the complete Stream Table is block moved BC bytes into higher memory. 
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4.1 INTRODUCTION 

The tape driver routines are designed to be called from 105 and interface with 

105 through the standard routine tables. Two interfaces to 105 are defined in 
the drive which correspond to cassette | and cassette 2. The routines which drive 


the two tape units use common code differing only in the set-up of motor number. 


The open routines are passed a parameter string which contains three optional 
fields:- 


- buffer length in units of 256 bytes, default is 4 
- no display option, default is display 
- filename, default is null. 


The buffer size is added to the working storage requirement of six bytes to give 
the total own memory requirement. The own memory area has the following structure:- 


low memory address offset g- start of own 


memory for tape driver 


offset 6= start of buffer 
area for tape drive 


| buffer size- buffer length*256 


- high memory address 
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The use of the working storage variables is as follows:- 


Variable Value 


FLAGS Bit Ø is SUPPRESS display of filenames on 
console during OPENIN routine. 
Bit 7 is the IN/OUT Flag set to 1 by OPENOUT set to Ø 
by OPENIN routines. 


BSTO Parameter String buffer length or default 4. 
S N Store for current value of В. 
CTEMP Store for current value of C. 


BC is the count of bytes to process and gives the 
Current position in the data buffer. 


TYPE Really a sequence number, on OUTPUT is used to 
write a correct sequence number to the tape block 
on INPUT used to verify block sequence. 


MOTOR Contains the COP Contro! motor number of one of 
the two cassettes. 
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4.1 INTRODUCTION 

The tape driver routines are designed to be called from IOS and interface with 
105 through the standard routine tables. Two interfaces to 105 are defined in 
the drive which correspond to cassette 1 and cassette 2. Тһе routines which drive 


the two tape units use common code differing only in the set-up of motor number. 


The open routines are passed a parameter string which contains three optional 
fields:- 


- buffer length in units of 256 bytes, default is 4 
- no display option, default is display 
- filename, default is null. 


The buffer size is added to the working storage requirement of six bytes to give 
the total own memory requirement. Тһе own memory area has the following structure:- 


low memory address offset g- start of own 


memory for tape driver 


offset 6= start of buffer 
area for tape drive 


buffer size- buffer length*256 


* high memory address — 
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Each block written to tape contains the following fields:- 


- block length, of two bytes is the number of data bytes in the 
block. 


- data, of (block length? bytes 


- type, one byte normally a sequence number but first block ОҒ a tape 
file has bit 7 set and last block has bit 6 set. 


- checksum, two bytes, is the sum of all block length, data and 
type bytes plus an offset value ЗЭН. 


- zeroes, nine bytes of trailer to accommodate cassette mechanism 
inaccuracies on stop/start. 


A file is written to or read from tape by three or more calls to the tape driver. 
An open routine is performed - for a write a block is written to tape the filename 
of which is defined in the parameter string; for a read the tape is scanned until 
à filename block is found with filename matching the parameter string filename 

(if no filename is specified then the first filename block encountered is retrieved). 
The corresponding input or output operation is then performed by calling the 
relevant driver routines and transferring one character per call. On input the 
Characters are transferred out of the buffer until the buffer empties when it is 
replenished from tape. On output characters are added into the buffer until full 
when the buffer is written to tape. Тһе tape operation is completed by issuing 

à close which for input does nothing, for output writes the current contcats of 
the buffer to tape in a short Close block. 


Any attempt to deviate from this sequence will result in error e.g. ittempting an 
input of a filename block, filename blocks can only he read by an open request. 
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42 OPENOUT - ТР10Р0, ТР20Р0 


Тһе value of motor number used in the cassette commands to the СОР is determined 
by the entry point into the OPENOUT routine. The input parameter string pointed 
to by HL of length BC, is of the following format: 


Cdufter лепат 0 J (Fi1ename] 


where "buffer length" is a string of numeric 
ASCII characters. 

"filename" is a string of ASCII characters not, 
starting with the ")" or "*" character 
C]indicates an optional field. 


The *buffer length: field is analysed by the routine TPSYN. The existence of 
this optional field is determined by the presence of the * character. If the 
field is present the following characters up to the :.character are exnected 

to be numeric and equate to a non-zero value. ТР5ҮМ and its routines make a very 
thorough check of this part of the parameter string and detect the following 
error conditions. 


- the parameter string length in BC greater than 255 

- поп-пштегіс characters between the * and : 

- all zero characters between the * and : 

= the character following the numerics is not a : ( if no more 


parameter string characters follow the buffer length field then 
the : is not mandatory). 
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If none of these conditions apply the numeric value of the buffer length is 
multiplied by 256 to give the actual buffer length in bytes. If the *buffer 
length: field is absent from the parameter string then the default buffer length 
is 4 which when multiplied by 256 gives an actual buffer size of 1024 bytes. 


The working storage requirements for the tape drives is 6 bytes which when 
added to the buffer size is set in BC and used as input to MKBUFF, section 3. 
Any errors detected either during parameter string analysis or insufficient 
room error from NKBUFF results in a direct return to 105, with Carry set and the 
accumulator containing 136, Syntax Error in Parameter String. 


On return from TPSYN, HL points to the start of Own memory. At offset ) the 
FLAGS variable is set with bit 7, the OUT flag as a one and if the optional 
parameter string field) is present bit 9, the SUPPRESS flag is set. Тһе remaining 
working storage variables are set as follows: 


Variable Value 
BSTO Buffer length (i.e. buffer size + 256) 
СТЕМР p 
BTEMP Buffer length 
TYPE ? 
MOTOR Either 8 if entered through TPlOPO 


or 2 if entered through TP20PO 
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With E set to 81H indicating a Mame Type data block, BC set to number of bytes 
remaining in the parameter string and HL pointing to the current position in the 
parameter string (start of filename if present), the routine WRSLCK, section 4.7, 
is jumped into. This writes the Name type block to tape, the data of which is 
the parameter string filename if present. Since WPBLCK has a RET statement at 
both normal and error endings control passes back to IOS after the execution of 
WRBLCK. 
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4.3 OUTPUT - TPOUT 


On entry the Out Flag Bit 7 of Flags offset zero in own memory is tested and if 
not set the routine immediately returns with Carry set and the error code 135 in 
the accumulator - Attempting to Write to Tape File opened for Input. The Out Flag 
is set by the OPENCUT routine and reset by the OPENIN routine. 


The entry conditions into an output routine from IOS is that the accumulator 
contains the character for output and HL points to start of own memory. 

TPOUT does not write a data byte each time it is called but accumulates data in 

its own memory buffer. The pointers into the buffer are held in the working storage 
variables BTEMP and CTEMP. LOBUFF is called which sets up BC, D and E from the 
working storage variables BTEMP, CTEMP, MOTOR and TYPE respectively. The HL 
contents are copied into IX and HL itself is set to point to start of the own 
memory buffer area. 


The lest written position in the tape buffer is computed by adding 8C to HL and 
the result decremented. The character in A is written to this computed location, 
BC is decremented and BC, D and E are saved in their respective working storage 
variables. This procedure has the effect of writing the first received data byte 
at the high address in the tape buffer and subsequent bytes in successively lower 
addresses, i.e. the data sequence in a tape block is in reverse order. 


After saving the registers, BC is tested and if non-zero, indicating buffer not 
full, the routine returns to caller, IOS. If BC is zero then the buffer is full. 
BC is reset to the buffer size, E is incremented to give the data block sequence 
number and bit 7 of E is reset to clear the Name type indicator. The new register 
contents are saved in working storage and WRBLCK, section 4.7, is jumped into. 
This writes a data block to tape, the data of which is an entire tape buffer 
contents. WRBLCK returns directly to 105. 
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4.4 OPENIN - TPIOPI, TP2OPI 


The operation of the OPENIN routines initially proceeds as for the OPENOUT 

routines, section 4.2. The motor number is determined by the entry point and 

TPSYN is called which analyses the parameter string up to the filename field and 
creates own memory via MKBUFF, The working storage variables are set up as follows:- 


Variables Value 


FLAGS А11 zero unless SUPPRESS specified in parameter 
string which would set Bit 0 


BSTO Buffer length defaults to 4 if the buffer length 
field is absent from the parameter string 


CTEMP Undefined 

BTEMP 0 

ТҮРЕ Undefined 

MOTOR tither 8 if entered through TPIOPT 


or 2 if entered through TP20PT 


Having performed the initial analysis and set-up the registers are saved and with 
BC containing the buffer size and D set to the motor number the routine RDBLCK, 
section 4.8, is called. This reads in a block from tape via the COP. BC 15 
returned as tape data block length and E as the Data Type or sequence number. 

If an error was detected by RDBLCK then the OPENIN routine returns to 105 with BC 
set to buffer size, DE set to current position in parameter string and HL pointing 
to the current position in the tape buffer. 
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1f OK the Data Type returned in E from ROBLCK is checked to be a Name Туре. 

If not then the routine loops back and another data block is read. If the input 
parameter string did not contain the filename field then any Name Type block is 
accepted by the routine. Otherwise the retrieved filename from the tape is compared 
with the parameter string filename. Іп all cases provided the SUPPRESS flag is 

not set, the retrieved filename is displayed on the console device (no error 
results if there isn't a stream 9) but if the input and output filenames do not 
match the routine loops and looks for the next Name Type block. The working 
storage variables TYPE and CTEMP are cleared and the routine returns to IOS with HL 
pointing to start of the filename and BC containing number of bytes in the filename. 
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4.4 OPENIN - TPIOPI, ТР20РІ 


The operation of the OPENIN routines initially proceeds as for the OPENOUT 
routines, section 4.2. The motor number is determined by the entry point and 

TPSYN is called which analyses the parameter string up to the filename field and 
creates own memory via MKBUFF, The working storage variables are set up as follows:- 


Variables Value 


FLAGS All zero unless SUPPRESS specified in parameter 
string which would set Bit 9 


BSTO Buffer length defaults to 4 if the buffer length 
field is absent from the parameter string 


CTEMP Undefined 

BTEMP ? 

TYPE Undefined 

MOTOR Either 8 if entered through ТР1ОРІ 


or e if entered through TP20PI 


Having performed the initial analysis and set-up the registers are saved and with 
BC containing the buffer size and D set to the motor number the routine RDBLCK, 
section 4.8, is called. This reads in a block from tape via the COP. BC 15 
returned as tape data block length and E as the Data Type or sequence number. 

1f an error was detected by RDBLCK then the OPENIN routine returns to 105 with BC 
set to buffer size, DE set to current position in parameter string and HL pointing 
to the current position in the tape buffer. 
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lf OK the Data Type returned in Е from RDBLCK is checked to Бе a Name Type. 

If not then the routine loops back and another data block is read. If the input 
parameter string did not contain the filename field then any Name Type block is 
accepted by the routine. Otherwise the retrieved filename from the tape is compared 
with the parameter string filename. Іп all cases provided the SUPPRESS flag is 

not set, the retrieved filename is displayed on the console device (no error 
results if there isn't a stream 9) but if the input and output filenames do not 
match the routine loops and looks for the next Name Type block. The working 
storage variables TYPE and CTEMP are cleared and the routine returns to 105 with HL 
pointing to start of the filename and BC containing number of bytes in the filename. 
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4.5 INPUT - TPINP 


On entry the Out Flag. bit 7 of FLAGS, pointed at by HL on entry from 105, is checked, 
and if set the routine immediately returns with Carry set and the error code 135 

in the accumulator - Attempting to Read from Tape File Open for Output. LDBUFF 

is called which sets up BC, D and E from the working storage variables BTEMP, CTEMP, 
MOTOR and TYPE respectively. IX is set to point at start of own memory and HL 
points at start of buffer. 


If the retrieved BC is zero indicating that the buffer is empty, then а data block 
must be read from tape. Prior to a call to RDBLCK the type of the previous 

block read in is checked not to have been a Close type by testing bit 6 of the 

TYPE working variable. If set then the INPUT routine should not now be called but 
rather an OPENIN routine. Carry is set and the routine returns with the accumulator 
containing the error code 133 - End of Data Error. 


RDBLCK, section 4.8., is called. Any errors detected causes an immediate return 

to 105 with Carry set. Тһе ТҮРЕ is again retrieved and incremented. This new 

value is compared with the value from RDBLCK returned to E. If they agree (and 

the check takes into account that the Close Bit 6 may be set) then the block just 
retrieved from tape has a sequence number one greater than the previously read block. 
The data block length returned by RDBLCK if zero, i.e. a null block, causes the 

next block to be read. 


When the buffer has some data in it, then a call to TPINP results in a character 
being moved from the buffer to the accumulator. Pointers into the buffer are 
maintained in working storage. The bytes are transferred first from a high address 
in the buffer pointed to by adding HL (start of buffer) and BC (characters yet to 
be transferred). Each time TPINP is called BC is decremented until when zero the 
next tape block is read. 
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4.6 CLOSE - TPCLS 


On entry from 105, HL points to start of own memory, in this case to the FLAGS 
variables. The Out Flag Bit 7 is tested and if a zero TPCLS returns immediately 
since on input no special action is required of the tape driver - at the end 

of each WRBLCK the COP is instructed with г NULLCOM command and is therefore not 
necessarily expecting any more cassette operations. 


If open for output the close routine must write the remaining contents of the 
buffer to tape. LDBUFF is called which sets up the current value of BC, D and E 
from BTEMP, CTEMP, MOTOR and TYPE respectively. The number of bytes to be written 
from the buffer is computed from the formula:- 


Buffer Size - BC where Buffer Size is held in BSTO 
BC is the current offset into the buffer. 


The resultant value is set in BC as the number of bytes to write; HL is set 
pointing at the first valid data byte and E is incremented to give the sequence 
number with bit 6 of E set to indicate a close block. WRBLCK, section 4.7, is 
jumped into and writes a close block the data of which is the remaining data 
bytes in the buffer when TPCLS was called. WRBLCK returns to 105. 
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4.7 


WRITE A TAPE BLOCK 

Entry: WRBLCK 
BC= number of bytes to write 
E = block type 
HL points to start of data 


Function: Write a block of data bytes to tape via the COP. 


Routines: TCHR 
CASSON 


Exit: No special conditions, Carry set if error detected. 


Params:  COPCTL * 


COPST * 
COPBUFF * 
CHKSUM * 


RSTB ж 
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The cassette command 89H is summed with the control bits RECORD @0Н and the 
selected MOTOR 084 or 92H (for MOTORI AND MOTOR2 respectively) to give the СОР 
command. The routine enters a loop which waits for the READY Bit 5 of COPST to 
go high. At this time COPST is reset to zeroes and the computed COP command set 
in COPCTL With interrupts enabled the CHKSUM variable is seeded with the value 
of HL which happens to be the address of COPCTL i.e. 38H. This whole operation 
is repeated. 


The second time that the COP interrupts and the handler sets the READY, will 
indicate that the contents of COPBUFF (which is random) will nave been written 
to the tape. 


Data is written to tape via the COP using the routine TCHR which parenthetically 

is defined as 7578. The number of bytes in the data block, fc, is written to tape, 
using TCHR register C first. WRBLCK then enters a loop which writes the content 

of the address pointed to by HL to tape using TCHR, decrements BC and increments HL. 
This loop is exited when BC reaches zero. Following the data the contents of 
register E, still as on entry to the routine, is written to tape. This may contain 
the value 81H indicating the block is a Name type; the data block sequence number; 
ог if bit 6 is set a Close type block. 


As TCHR writes each byte to COPBUFF and waits for a COP interrupt, it additionally 
sums the data byte into the double precision CHKSUM and redefines itself as RST8. 
The checksum is written low byte first after the E register and is the sum of all 
written bytes starting with register C and ending with register Е plus an offset 
equal to 3BH, As a trailer nine zero bytes are written, the COP is commanded 
with a null command D9H and the routine returns. 


If TCHR detects an error from the COP, CERR Bit 4 of COPST set, then the error 
return is to WRBLCK' S caller. 
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READ A TAPE BLOCK 


Entry: ROBLCK 
BC = Buffer Size 
HL points to start of buffer area 


Function: Read a block of data bytes from tape via the COP 


Routines: TCHR 
CASSON 


Exit: BC = tape block size 
Е = data type or sequence number 
Carry set if error. If so A contains error code 
131 Length Error, data block will not fit in buffer 
132 Checksum Error, computed checksum as data read in from 
tape differs from tape block checksum. 
130 Hardware error, returned by the COP through COPBUFF 
Params: COPCTL * 
cop * 
COPBUFF * 
CHKSUM * 
RSTB * 
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The cassette command 87H is summed with the control bits PLAYBK 94H and the 
selected MOTOR 98H or 92H (for MOTOR 1 and MOTOR 2 respectively) to give the 

COP command. The routine then behaves similarly to WRKBCK - waiting for the COP 
to become READY, setting COPCTL with the computed COP command seeding the CHKSUM 
with the address COPCTL, and repeating the sequence so that the undefined byte 
written by WRBLCK in front of each tape block is retrieved and ignored. In fact 
three iterations have to be performed to retrieve this leading undefined byte:- 


- first READY interrupt is received and COPCTL is set with the 
cassette command. 


- at the time of the second READY interrupt the COP interrupt 
handler, section 2.5.1., sends the cassette command. 


- by the third interrupt the undefined data byte will have been 
set in COPBUFF. 


Data is read from tape, via the COP, using the routine TCHR, also used to write to 
tape by WRBLCK. The first two bytes retrieved by TCHR contain the block size of 
the data block being read. This is recovered into DE and compared with BC which 
ап entry to RDBLCK is the size of the destination buffer. If the block size is 


greater than the buffer size then this results in an error code 131, Length 
Error, set in the accumulator and a return made to caller with Carry set. Otherwise 


RDBLCK enters a loop which reads DE bytes into the buffer starting at the buffer 
start address. When all data bytes have been read into the buffer the next byte to 
be recovered is the Data Type or sequence number. The checksum bytes are read via 
TCHR and compared with the computed value maintained by TCHR up to and including 
the retrieval of the Data Type byte. If these differ an error code 132, Checksum 
Error, is set in the accumulator and Carry is set. = 


The СОР is commanded with the null command DH and the routine returns. 
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5.1 INTRODUCTION 
Three device drivers are supported by Х10:- 
- T10, driver for a TV device 
- LIIO, driver for the VF display 
- TLIO, driver for concurrent TY and VF displays 


One set of code modules support these drivers with different entry points for 
each of the devices. Generally, TVIO and TLIO operate identically and, with 
the exception of OPEN, the same entry points. No distinction is made between 
OPENIN or OPENOUT for these devices and once opened the devices may be written 
to or read from. 


The own memory is composed of a fixed portion, the working sterage and а 
variable portion which is the display buffer. For TV devices which have page 
zero EXCESS value of 24 the start address of the display buffer within own 
memory is required to be of the form:- 


64n + (11/20) where n is an integer in the range 
1<п<511 
LL is the line length either 40 
or 80 characters per line. 


Sufficient own memory must be requested by these TV device types so that the 
display buffer will fit no matter what MKBUFF returns as the own memory start 
address. The own memory layout is as follows:- 


06110У81-Ү0-СР5 


NENBRALN-TECH-5. 1 


02.00 


low mesory address 


Offset to CSTO 


тібі 
Р 

2 

[3 

FLAGS 

EXFLGS 

w 

"WIN 


High селағу address 


TY Mode 
Unused 

Unused 

Depth, no. of display lines held in buffer 
Line length, ro. of display characters 
Excess + Line Length, total bytes per line 
Flags 

Extra Flags 


Line Number, count of lines from top of 
display to current Tine (offset 2) 

Frame, count of lines within buffer to 
first display line (offset 2) 

Window, no. of characters in cursor line to 
start of 16 character VF window 


Initial 8 value as start of input line 
Initial C value as start of input line 
Tesporary storage 
Temporary storage 
For TV devices with EXCESS 24 unused 
locations so that TV buffer starts on 
беп + (LL/20) boundary 
Storage for registers С 

8 

t 

D 
Flag Store 
Display buffer Ist location 


Display buffer 


End bytes 
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The three flag variables contain the following: 


Variable Flag Bit Indicates 
FLAGS SFTFLG 7 1 = Attribute on 
IFLG 6 Insert key depressed, destroyed by 
any control key 
CNSFLG 5 This is the console device 
CSIFLG 4 Not Used 
XYFLG 3 User sending cursor xy coordinates 
YFLG 2 @=expecting x coordinates 1=expecting 
y coordinate 
ESCFLG 1 ESC key has been depressed 
TVMFLG 2 Control W, the TY Node Control has 
been depressed 
EXFLGS SNDCCFLG 7 User has requested the character at 
cursor position 
SNDXYFLG 6 User has requested xy coordinates of cursor 
SNDYFLG 5 B= send x coordinate 
1- send y coordinate 
CURSHOFLG 4 Show cursor 
3-2 Unused 
FLGSTO TVFLG 7 Driver supports video display 
CHRFLG 6 Characters for sending in input mode 
LIFLG 5 Driver supports VF display 
INPFLG 4 Editor in input mode 
OLFLG 3 Опе line display set for VF and if 
TV depth - 1 
PGEFLG 2 Page return mode 
HLDFLG 1 Hold mode 


CRFLG ғ Carriage Return depressed 
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The own memory working storage variables are used both as an interface between 
X10 and XEDIT and by XEDIT routines alone. Тһе use of the registers B, С, D 
and E is significant and these are always stored in the working storage 
variables BSTO, CSTO, 0570 and ESTO prior to returning to 105 for every 105 
request, except CLOSE. 


Register Contents 


B The y coordinate within the current line of 
the cursor (offset 9) 

с Тһе x coordinate within the current line of 
the cursor (offset 0) 

D The number of full screen lines in the current 

line 

The character count of the last line of the 

current line. 


m 


These values may be shown graphically as follows: 


FLGSTO 


Usual 
position of. 
HL pointer 


Current Line 


Excess 


4 End Bytes 
Conceptual TV Buffer 
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All cursor and memory positional information is held as offset zero. So if 
the cursor is positioned at the extreme left of the first line of the current 
line B and C contain zeroes. GETCUR a frequently executed routine calculates 
the memory address of the cursor position from the expression: 


HL + IN * EL +В + C 1 


where HL contains the address of display buffer -1 
i.e. FLGSTO address 

LN is the line number of the current line in the 
display buffer (offset P) 

EL is the total bytes per line, characters * excess. 


So if B, C and LN are zero the result is HL + 1, the first buffer location. 
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5.2 OPEN - TVOPIN, LIOPIN, TLOPIN 
The OPEN routines perform the following operations:- 
- syntax checking 
- own memory sizing and a call to MKBUFF 
- own menory initialisation 
- blanks the display 
5.2.1 TWOPIN 
5.2.1.1 Syntax 
The routine TVSYN is called. This makes an immediate check that the Mains 
Present Bit 2 of the Status Register is set and if not returns to TVOPIN with 
error code 111, No Mains Present. Тһе default values of DEPTH, 24, and TVLEN, 40, 
are defined and if the parameter string length is zero then these values are 
retained. 
The format of the parameter string is:- 
/ inm] ^ where S/L is the optional short/long field 
Corresponding to 40/80 characters per line 
by defauit S. 
nnn is an optional depth field which is the 


number of screen lines held in memory, by 
default 24. 


% 
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The routine will return with a Syntax Error, code 110, if any of the following 
conditions are detected:- 


- BC, the parameter string length greater than 255 
- the first character of nnn is non numeric 
~ nnn evaluates to zero 


The EXCESS parameter is extracted from page zero and for the 40 character per 
line devices is added to 40 to give the total number of bytes per line as 
required by the video hardware. For 80 character per line systems the EXCESS 
value 15 doubled prior to being summed with 80. The bytes per line values 
which may occur are 44 or 88 and 64 or 128 corresponding to EXCESS values of 4 
and 24. 


5.2.1.2 Sizing Own Метогу 

As described in the Introduction, section 5.1, the physical start addresses of 
TV buffer for devices with page zero EXCESS of 24 are required to be of the form 
64n + 2 for 40 characters per line and 64n + 4 for 80 character per line systems. 
The actual memory requested from MKBUFF 15:- 


(90 + (total bytes per line * depth)) bytes 


The total bytes per line * depth gives the size of the Ту buffer. Тһе 90 byte 
overhead is comprised of:- 


- 22 bytes of working storage variables 
- 64 bytes so that the TV buffer can start at а 64n + C 


address по matter where MKBUFF specifies the offset Ø byte 
of own memory 
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- 4 bytes to store the end of buffer code. 


For devices with page zero EXCESS of 4, the corresponding own memory requirement 
is defined as:- 


(26 + (total bytes per line * depth)) bytes 


These devices can accept any start address for the TV buffer and consequently 
do not require the additional 64 byte overhead of EXCESS 24 systems. 


Having computed own menory requirements, MKBUFF is called. 1f insufficient 
memory is available the OPEN routine returns to IOS immediately. 


5.2.1.3 Memory [nitialisation 


1f the device being opened is the console device, indicated by its stream 
number being zero, then the following page zero variables are set up:- 


- PZLEN 10 for 40 character per line systems 
17 for 80 character per line systems 


-  PLLEN set to the characters per line, 40 or 80. 


The following working storage variables are then initialised. 
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Variable Value 

TVMDI Zeroes for 40 character per line devices 
Bit 6 set for 80 character per line devices 

DEP Depth Value up till this time stored in D 

ш Line Length, по. of characters per line, 40 
or 80 up till this time stored іп 8 

EL Excess + Line Length, total bytes per line, 
up till this time stored in C 

FLAGS CNSFLG, Bit 5 set if console device. 


Otherwise all zeroes. 


Zeroes are written to own memory locations offset 8 to 16 that is the variables 
EXFLGS, LN, FRM, WIN, INPB, INPC, CHAR, DCHR. The CSTO Offset variable at 

offset Ø of own memory is calculated by the subroutine CALFILE. This determines 
the offset of the CSTO variable such that the TV buffer store, which starts +5 
locations from CSTO, is set on its required memory boundary. So for 40 character 
per line devices with an EXCESS of 24, CALFILE calculates the next address beyond 
the first 16 working storage variables (the IX variables), which is of the form 
64n - 3. This value is set in own memory at offset 9. By executing GETREG, TVSYN 
exits having positioned on FLGSTO, offset -1 from start of TV buffer. 


On return from TVSYN, IOPON, section 2.9, is called. Тһе TVPLG Bit 7 of FLGSTO 
is set and if the depth value is 1, One Line Flag, OLFLG, Bit 3 of FLGSTO is set. 


5.2.1.4 Display Blanking 


The Clear Page contro! character IF is set in the accumulator and the routine OUT2 
called. This is an entry point in the TVOUT routine section 5.3. This has the ~ 
effect of blanking the display and positioning the cursor at the top left hand 
corner. On return from 0072, HL is positioned one byte beyond the TV buffer by 
“calling GETCR@ with the Accumulator set to the depth. 00<<расе><5расе> is written 
to the four locations following the TY buffer which instructs the hardware that 
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this is the end of TV memory. TVOPIN then returns to 105. 


5.2.2 LIOPIN 


The parameter string for the VF display driver is of the form:- 
nnn where nnn is a numeric ASCII character string 
The string specifies the number of bytes as buffer for the VF display. The 
syntax checking detects the following errors which result in a Syntax Error 
code 110 being passed back to 105:- 
- parameter string length in BC greater than 255 bytes 
first character in string is non-numeric 


- string evaluates to a number less than 16. 


If no parameter string is passed to LIOPIN, BC = g, then the default VF buffer 
size is 80 bytes. The registers are set up as follows:- 


Register Value 


VF Buffer Length corresponding with line length 


c VF Buffer Length corresponding to total bytes 
per line 
D 1, corresponding to a depth of 1 


E as on entry from 105, the stream number 
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The routine LIOP is called which is an entry within TVSYN, corresponding to 
sections 5.2.1.2 and 5.2.1.3 which size own memory, call MKBUFF and initialise 
own memory. On return from TVSYN the FLGSTO variable is set with LIFLG, Bit 5 
and OLFLG, Bit 3. The routine jumps to OPEN common to all drivers and 
described in section 5.2.1.4. 


5.2.3 TLOPIN 


Behaves almost identically with TVOPIN except for the flag settings in FLGSTO 
with the additional flag LIFLG Bit 5 set, indicating the VF display. 
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5.3 WRITE - TVOUT, OUTI, TVOUT 


One routine performs the output for all three drivers. Тһе entry point for 
ТУ10 and TLIO is the same and is a call to the routine TVST which enables 

the TV display. The next statement is the entry point for the VF driver, 0071. 
which is a call to GETREG which reinstates the registers C, B, E, 0 from CSTO, 8STO, 
ESTO and DSTO, respectively and sets HL pointing to the FLCSTO variable. The 

next statement is the entry point OUT2, used by the OPEN routines and is a 

Call to OUT. On return the common exit code INEND is entered which performs 

the following:- 


- if the device is the console, CNSFLG of FLAGS set, the 
page zero variable PHPOS is set to the cursor position 
(offset 1) 


- if the CURSHOFLG of EXFLGS is set the SHOCUR routine is 
called which for TV devices manipulates TV1, TV2, ТУЗ 
and TVCUR of page zero so that a cursor is displayed, see 
section 5.4 


- stores D, E, B, C in their corresponding working storage 
variables 


— returns to 105. 
5.3.1 TVST 


Calls REMCR@ which with interrupts disabled sets bit 7 of TV2, the display bit, 
and resets all other bits. If bit 6 of TV2 was set on entry indicating that the 
cursor is currently being displayed then the character at cursor position held 

in TVI is set at the cursor position within the TV buffer the address of which is 
“іп TVCUR. With bit 7 of TV2 set the video is enabled at the next Frame Interrupt. 
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On return the page zero location TYRAM is set with the address of start of own 
memory. 


5.3.2 GETREG 


On entry expects HL to be pointing at start of own memory. At offset 0 of own 
memory is contained the offset to the location of the variable CSTO. The values 
in CSTO, BSTO, ESTO and 0572 are set into their respective registers leaving HL 
pointing at FLGSTO i.e. offset - relative to the start of TV buffer. RST8 is 
seeded with the address of the GETCUR routine. 


5.3.3 our 


The flags indicating that the driver is currently sending characters are reset. 
These are:- 


- PGEFLAG, of FLASTO, driver sending a page 

- CHRFLG, of FLGSTO, driver sending characters 

- SNDCCFLG, of EXFLGS, driver sending character at cursor 
Y 

7 SNDXYFLAG. | ot ExFLGS, driver sending cursor position 

- SNDYFLG 

If any of the receive flags are set, Tufts, ESCFLG, YFLG, XYFLG, indicating 

that the driver is expecting to receive special control characters, then the 

EDITA is called imediately, section 6. 


Otherwise the character in the accumulator to be output is inspected and if 

it is the carriage return character ØD, then the following output code is called 
so that on return the line-feed character ФА may be set in the accumulator and 
the output code executed normally. For non one-line devices this means an 
immediate call to EDITA. 
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For one-line devices, those with OLFLG of FLGSTO set, further analysis is required:- 


- if the character for output is line-feed, this is 
ignored and OUT returns to caller having reset CHRFLG 


- if the CRFLG of FLGSTO is set, it means that the driver 
is waiting for a Carriage Return character as acknowledgement 
of the current display. If the character is CR then OUT 
returns immediately, if not it enters a wait loop 
which rejects any key other than in line cursor positioning 
or Newline. 


- lf the CRFLG is clear then the EDITA is called irmediately. 


The EDITA sets the character passed in the accumulator into the TV or VF 
buffer, or if a contro! character performs the necessary manipulation. A 
full description of XEDIT is given in section 6. 


On return SETWIN is called which tests the LIFLG of FLGSTO. If this is not 
set, indicating the VF display does mot have to be driven, then the stack is 
popped and a return made to OUT's caller, TVOUT. 


If LIFLG is set SETWIN checks that the position of the cursor in the current 
line, in C, is within 15 characters of the notional start of window stored in 
the working storage variable WIN : WIN is the number of characters to the 

start of the 16 character window in the cursor line. If C is less than or equal 
to WIN then the contents of C are written to the WIN variable so the cursor 
appears at first character in window. If C is in the range WIN<C<WIN + 15 then 
no window adjustment is needed and SETWIN returns. Otherwise the WIN value is 
adjusted so that the cursor appears as the last character in the window unless 
this happens to be one character beyond the end of line in which case the window 
"does not include the cursor. 
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On return from SETWIN, the accumulator is cleared and WR jumped into. This 
initially calls GETCUR through RST8 with C set to WIN which on return ensures 
that HL points to the first character in the 16 character window. 


The value of A on entry is used to determine the offset of the cursor in the 
window. With A set to zero no cursor will be displayed (the COP actually 
sets the cursor at any character which has bit 7 set) 


With HL pointina at the window position in the VF or TY buffer and DE pointing 
at the end of COPBUFF, the WR routine enters a loop which copies 16 

bytes from the buffer into COPBUFF by incrementing HL and decrementing DE. 
This has the effect of writing the data to COPBUFF in reverse order. 


COPST is read with interrupts disabled and if READY is set then a DISPCOM 
command is written to COPCTL and the routine exits back to IOS. If READY is 
not zero then if the command in COPCTL is DISPCOM the program routine exits 

to 105; оғ if the command is NULLCOM, DISPCOM is set in COPCTL and the routine 
exits to 105. Any other command causes the routine to loop until READY is set 
or COPCTL contains DISPCOM or NULLCOH. 


The transfer of the data bytes from COPBUFF to the COP is performed by the COP 
interrupt handler, section 2.5.1. 
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5.4 READ - TVINP, INPI, TVINP. 


The TVIO and TLIO both have the same entry point which is a call to TVST, 
section 5.3.1. The next statement is the entry point for 1110 and is a call 
to GETREG, section 5.3.2. 


The EXFLGS are examined to determine if a special send character is expected 
by the user:- 


- if SNDCCFLG, bit 7 is set, then the user is expecting to be 
sent the character at cursor position. This is obtained by 
calling GETCUR through RST8 which calculates the current 
position and returns the character at that address in the 
accumulator. Тһе special send flags are cleared. 


- if SNDXYFLG, bit 6, is set, then if SNDYFLG is not set then 
the accumulator is set to C + l, the screen x coordinate 
(offset 1). The SNOYFLG is set prior to returning to 105. 


- if SNDYFLG, bit 5, is set, then the y screen coordinate is 
calculated from LN + B + 1, where LN is the line number 
variable. The special send flags are cleared. 


ІҒ any of these flags are set TVINP makes a return to 105 with the required 
value set in the accumulator. 


If no special send flags are set the routine enters the input mode. INPFLG, 
Bit 4 of FLGSTO, is set and XYFLG and YFLG of FLAGS are reset in case the 
driver was in the process of receiving cursor xy coordinates from the user. 
The CHRFLG is tested and if set indicates that characters are already being 
transferred to the user. The routine branches to the location GOTCHS, 5.4.2. 
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5.4.1 Get Characters from Keyboard 


If CHPFLG is zero. then this is the first call for a character on the current input 
request. INPB and INPC are set with the contents of B and C which will be zero 

if the cursor is positioned at the extreme left of the display on the first line 
of the current line. 1f either B or C are non-zero, indicating that a prompt 

has been output to the current line, then the HLDFLG, Bit 1 of FLGSTO, is set 
disabling cursor positioning off the current line or into the prompt. TVINP 

then enters à loop which recovers characters from the keyboard until a Carriage 
Return character is detected. Тһе operations are:- 


- CALL WRC, which sets the cursor on the VF display by setting 
the accumulator to be the offset of the cursor position within 
its 16 character window, and then executing WP, described in 
section 5.3.3. 


- CALL SHOCUR, which sets the cursor on the TV display. This 
sets up the following page zero variables so that on the next 
Frame Interrupt a cursor will be displayed:- 


- TVCUR, set to the memory address which is the current 
position of the cursor. This is normally the next 
input position unless the next input position would be 
on the next line in which case the cursor position 
is at the last input position. 


- TVI, set to the value of the character found at cursor 
position. 

- TV2, sets bit 6, so that cursor is displayed and if 
positioned at the end of a line or CRFLG set, bit 5 
is set which selects the cursor blob character rather 
than underline. 
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- TW, the flash clock is set to 10H so that the cursor 
immediately appears and remains for approximately 
a third of a second. 


- CALL RDKEY, gets a keyboard key and converts it to an ASCII 
character in the accumulator, see section 7. 


- САШ. REMCUR, which for TV devices executes REMCRO, as 
described in section 5 


-1, which disables the cursor and 
Sets the character at cursor position. This is done since 
EDITA expects a "clean" display buffer. 


- САЦ. EDITA, which sets the character received by RDKEY into the 
display store. 1f the character is Carriage Return, then EDITA 
sets CHPFLG. 


- Test CHRFLG, if zero repeats the loop. 


When CHRFLG becomes set, HOLD of XEDIT is called which simply resets B and C 
with their original values as stored in INPB and INPC ready for transfer of 
Characters back to the user. 


5.4.2 GOTCHS 


This passes a character back to the user from the current input line. CRFLG is 
reset, the accumulator and INPB and INPC are cleared. Dand E which define the 
position of the last character of the current line are compared with B and C, 

the current position in the line. If they differ indicating more characters 

are to be sent to user, the menory location corresponding to the values of B and 
C is determined via GETCUR, and the character at that location extracted. CURRT 
is called which normally just increments the register pair BC but if at the end of 
Tine, but not end of the input line, B is incremented and С is set so that the 
continuation line character is bypassed. 
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On return from CURRT, GOTCHS jumps into the common exit code INEND. 


Eventually all characters will be transferred so that BC exceeds DE on 

entry to GOTCHS. The flags CRFLG and CHPFLG are set, the HLDFLG is reset, 

and BC are cleared. А Line-Feed is output through OUT, section 5.3.3 and 

if tn& PGEFLG is not set the accumulator is set to the Carriage Return character 
9D, INEND is executed. If PGEFLG is set, then if the page is completely sent, 
indicated by LN being zero, INEND is executed with A set to 9D after resetting 
PGEFLG and CHRFLG. If the page is still being sent IMEND is executed 
immediately. 
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5.5 CLOSE - TVCLS, TVCLS1, TVCLS 


The current TV display device has its start of own memory address stored in 
the page zero location TVRAM. If the TV device being closed has the same 
start of own memory address then TV2 is cleared which switches off the video 
after the next Frame Interrupt. For all devices ТҮСІ1 is executed which 
jumps to IOPOFF, decrementing the V3 power use count in lOPUC and switching 
it off if IOPUC becomes zero. The IOPOFF return passes control back to 105. 
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5.6 MOVE - RESET, 2. RESET 


Called by 105 when own memory start address changes when a stream is removed. 
CALFILE is called which calculates the offset to CSTO so that the TV buffer 
Starts on the correct memory boundary. ІҒ this is the same as previously 
i.e. as stored at offset Й of own memory, the RESET returns to 105. 


If the new CALFILE value differs from the old value then the CSTO, BSTO, 
ESTO, DSTO, TV Buffer and 4 end bytes are block moved to the new position 
which is set at offset 0 in own memory. 
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6.1 INTRODUCTION 


XEDIT is called Бу XIO through the entry location EDITA. Both modules use the 
display own memory and the display values of BCOEHL, described in section 5.1. 
The edit character is passed to EDITA in the Accumulator and may be a character 
for insertion into the display buffer, or a control character. 


Certain characters within the display buffer are used by XEDIT for control 
purposes: ~ 


-~ E , the blob of value 7FH, is used as a continuation 
character for multi-line displays. When а functional 
line exceeds a display line in length the continuation 
character is set at the first character position of 
subsequent lines. 


- Ø when followed by spaces to a buffer line end causes 
the video hardware to cease making Bus Requests for the 
remainder of the line. This has the effect of making the 
bus more available to the 280, when the display is only 
partially in full, with consequent throughput enhancement. 
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6.2 MAIN LINE 


On entry the character in the Accumulator is stored in CHAR. Тһе HL pointer 
is incremented to point at the first location of the buffer store. If the 
character at this position is the line continuation character, blob, then 
this is set to the space character. 


The HL pointer is decremented restoring it to its normal position or FLGSTO. 
With the edit character both in the Accumulator and CHAR the EDIT routine 
is called which performs the edit operation on the buffer store and the 
control registers, 8, C, D, E. On return, the FRM variable is adjusted if 
necessary and the hardware switch-off code, @<space>, is set at the end of 
the current line. 


DOFRM is called which calculates the number of lines from top of the buffer 
to the cursor line equal to LN48. This is compared with the value of FRM 
which for a TV buffer indicates the start line (offset 2) of the 24 line 
display. The following may apply:- 


-  LNSB-FRM, i.e. cursor position is above the frame; FRM 
is set to the value LN«B so the cursor line appears as 
first line of frame. 


- РЕМ LN+B « FRM+23, i.e. cursor position is within the 
current frame; FRM is unchanged. 


- 2 LN+B > FRM+23, i.e. cursor position is below the frame; 
FRM is set so that the cursor line is last line of the 
frame. 


On return from DOFRM, HL is saved and DELZER is called. This calls GETCUR with 
B, C set to D, Ø so that HL points to first character of last line of current line. 
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If E is equal to the line length LL then the routine returns. Each character 
back from the line end to the Eth character is checked to be a zero. If no 
zero is found the routine returns, otherwise the zero is replaced by a space 
character. This is to remove any zeroes left behind by the EDIT operation 
e.g. character deletion. 


Unless the last line of the current line is full, the greater of E or C is added 
to the line start address and a zero written to the resulting location. With 
HL pointing to FLGSTO and B, C, D, E as modified by the EDIT function the 
program returns to caller. 
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6.3 EDIT 


The EDIT routine is called with the edit character in the Accumulator and 
CHAR. The value of flag settings and the edit character are tested to determine 
the edit function to be performed:- 


if XYFLG set, indicates that editor expects a cursor 
coordinate edit character. Section 6.3.1. 


- if TVMFLG set, indicates that editor expects а TV mode 
value. Section 6.3.2. 


- if ESCFLG set, indicates that whatever the value of the 
edit character this should be inserted into the buffer 
Store. Section 6.3.3. 


- if the edit character is not a control character then it is 
to be inserted into the buffer store. Section 6.3.3. 


- if HLDFLG and OLFLG not set, indicates that all control 
characters are valid, so the control request in the 
Accumulator is actioned. Section 6.3.4. 


- If HLDFLG or OLFLG set, indicating cannot move off current 
line or one line display respectively, then certain control 
codes are invalid and others are translated into one line 
equivalents:- 
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- IL, IK, Insert Line 

- DL, 2H, Delete Line 

- МР, 12H, Make new Line 

- М5, 13H, Make continuation line 


are invalid 
converted to NULL 


- CLEAR, IFH, Clear Page is converted 
to CLL, ICH, Clear Line 

- ҒҒ, CH, Home is converted to CHL, 1CH, 
Cursor Home Left. 


The resultant code is processed. Section 6.3.4. 
lnless specified the CRFLG is always reset after the EDIT operation. 
6.3.1 Set Cursor Position, SETXY 


The control code 16H sets the XYFLG, Bit 3 of FLAGS. EDIT expects the next two 
characters received to be the x and y coordinates of the cursor offset l, i.e. 
the x, y coordinates of the screen top left hand cursor is sent as 1, 1. If 
YFLG is set then the x coordinate has already been received and the current 
character in the Accumulator is the value of the y coordinate. 


If YFLG is not set, the contents of the Accumulator are saved on the stack and 
the routine HOME called. This sets B and C to zero. The Accumulator contents 
are restored. If A equals zero then the routine returns immediately with 
carry clear. In this case a coordinate of zero is considered as а coordinate 
of one. А is decremented (to offset Ø), compared with the line length and if 
greater set to the line length. The resultant value is set in C. On exit from 
SETXY the YFLG is set. 


On the second pass through SETXY, the YFLG will be set and the character in 
the Accumulator is the cursor y coordinate. The XYFLG and YFLG are both reset. 
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The contents of the Accumulator are tested and if zero the routine returns. The 
routine will also return immediately if the value of the y coordinate is 1 
corresponding to the top line of the display buffer. Otherwise LNFD is called 
А-1 times which line feeds to the required y coordinate incrementing the B 
register each time it is called. 


6.3.2 Set TV Mode, TVMSET 


The control code 17H sets the TVMFLG, Bit 0 of FLAGS, for Video devices. EDIT 
expects that the next character received is a TV mode control byte and this is 
set in the own memory working storage variable TVMDI. Тһе contents of TVMDI 
are output to the TY Control Register, port 12, at Frame interrupt time via 

the XEDIT routine SETFRM. This routine also computes the start address within 
the display buffer from which the video hardware is to start accessing. This is 
set in BC. 


6.3.3 Insert Character in Display Buffer, INSERT 


The character in the Accumulator and copied in the CHAR location is to be inserted 
into the display buffer at the cursor position specified by B and C. Оп entry 

all the IX flags except SFTFLG in FLAGS are set to zero. If the SFTFLG is set 
then the bit 7 of the character passed to EDITA is complemented. ІҒ the resulting 
Character is fH, EDIT returns immediately. Тһе current value of B and C are 
checked to be within or beyond the current line and not in the INPUT prompt area. 
If not carry is set and EDIT returns. The insert flag IFLG is tested which is 

set when the control code ТІН has been passed to EDIT. If set the routine branches 
to INSNOW, section 6.3.3.1. 


The CRFLG is tested. This is set by XIO when all characters have been passed 

to the User in input mode, section 5.4.2. ІҒ CRFLG is set then it indicates to 

the editor that the cursor is positioned at the start of a line and that that line 
must be deleted from the buffer to make way for the first character of a new current 
line. 
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DLINE is called which deletes the current line and any continuation lines that 
may exist. CPDB is called which returns with carry clear if BC is beyond the 
current line or carry set if within the current line. If carry clear then E 
is set equal to C marking the new end of the current line and INCDE called. 
This increments E the character count of the last line of the current line and 
conditionally increments D if E is equal to the line length. 


CURRT and CURLT are called. The reason for this seemingly worthless operation 

is to position the cursor correctly when inserting the first real character of 

à continuation line. The cursor at this time is positioned on the last character 
of the previous line. CURRT positions it two positions beyond the blob character 
and CURLT moves it adjacent to the blob. The actual address of this location is 
computed using GETCUR and the character in CHAR inserted. CURRT is executed 

and EDIT returns. 


6.3.3.1 Insert Mode, INSNOW 


IFLG is set as a result of depressing the INSERT keyboard key. In this 

mode characters entered within the current line cause all others to the right 
and below the cursor position to be shifted to the right. CPDB is called which 
determines whether the cursor is within or beyond the current line. If beyond 
then E is set equal to C marking the new end of the line. INCDE is called which 
increments the total character count for the line. Starting with the cursor 
line the characters to the right of the cursor are moved to the right. HL is 
set pointing to the cursor position location via GETCUR. The character at this 
location is retrieved into the accumulator and the input character now in C is 
written at HL. HL is incremented, the accumulator contents are moved to C and 
the process repeated unti! the end of line is reached. 


This operation is repeated for each line beyond the original cursor line with B 
incremented each time and C set to 1 bypessing the continuation character. 
CURRT is executed and EDIT returns. 
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6.3.4 Control Functions 


The character in the Accumulator is set in CHAR since the control character in A 
may have been modified by EDIT, see section 6.3. A table of control routines 
EDADD is indexed by A and the control routine executed. On completion of the 
control function the contro] routine returns to EDIT's caller. 


The following subsections detail the operation of each control routine. The 
control functions are summarised in the Table 6.3.4, overleaf. 


6.8.4.0 on, Control e, NULL, Null 
Does nothing, returns immediately. 
6.3.4.) 1H, Control A, INSLIN, Insert Line 


INSLIN uses the general insert line routine ILIN which makes space for a line 
to be added to the current line. On entry to INSLIN, ABCDE are zeroised and 

A is set to the value of LN, prior to the execution of ILIN. The general entry 
condition for ІШІМ is that the Accumulator contains the line number offset 0 
which is to be vacated making way for the line yet to be inserted. If the line 
to be vacated is the iast line on the display then all lines are scrolled up and 
the first line is lost. If not the last line of the display then the line to 

be vacated and all lines below it are scrolled down and the last lime is lost. 
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Table 6.3.4 

HEX. DECIMAL CONTROL KEY 

0 0 e Null 

1 1 А Sh/insert Insert line 

2 2 в 5һ/% Delete Line 

3 3 с Cnt]/newline Send page 

4 4 D End of file 

5 5 E Send line 

6 6 F Show cursor 

7 7 6 Cursor off 

8 8 H + Cursor left 

9 9 1 Cntl/escape Tab 8 spaces 

А 10 J + Cursor down 

B n K + Сиг$ог ир 

с 12 L Home Cursor home 

D 13 M Newline New] ine 

Е 14 N 5һ/% Attribute on 

p 15 0 Sh/escape Attribute off 

10 16 P Graphics escape 

n 17 94 Insert Enter insert mode 

12 18 R Grph/+ Make new line 

13 19 5 Grph/+ Make continuation Tine 
14 20 T Grph/newl ine Send cursor character 
15 21 у Grph/insert Send x, y 

16 22 ү cnti / insert Set cursor x, у 

17 23 W Grph/escape Set TV control 

18 24 x Sh/« Delete left 

19 25 Y Sh/> Delete character 

ЛА 26 1 E Cursor right 

18 27 t Escape Escape next character 
1с 28 1 Cntl/e Cursor home left 
10 29 \ Cntl/> Cursor home right 

1E 30 + Cntl/home Clear line 

1Е 31 -(£)  Shift/home Clear page 
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6.3.4.2 2H, Control B. DELLIN, Delete Line 

SCROLL is called 041 times with A set to LN. SCROLL moves lines below that 
specified in the Accumulator up one line. The functional line in which the 
cursor is positioned on entry is thus removed. The line immediately below 
the deleted line becomes the current line, BC contains zeroes and D and E 
аге computed for this new line by executing LNFD4, which counts the number 
of continuation lines and the number of characters in the last line. 
6.3.4.3 3H. Control C, PGERET, Send Page 

If HLDFLG is set returns immediately otherwise sets PGEFLG. LN is set to 
zero and the D and E values of the first line computed. Subsequent calls 
for input through XIO will return the whole functional screen unless cancelled 
by à call to output. 

6.3.4.4 4H, Control D, NULL, End of File 

Does nothing, returns immediately. 

6.3.4.5 5H, Control E, LNERET, Send Line 

Subsequent calls to input will return the current line. 

6.3.4.6 6H, Control F, SHOWC, Show Cursor 

Sets the CURSHOFLG and returns. 


6.3.4.7 7H, Control G, HLDEC, Cursor Off 


Resets the CURSHOFLG and returns. 
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6.3.4.8 8H, Control H, CURLT, Cursor Left 


If the LIFLG is not set then B and C are compared with INPB and INPC which 
mark the start of input position of the current line. If B and C are equal 
to INPB and INPC respectively then the cursor cannot move further left so 
routine returns. For single line displays the cursor may move left to 
inspect the prompt but data may not be input. 


The cursor is moved left by decrementing C, decrementing B if C becomes 1 
оп a continuation line. In this case C is set to LL-1. 


6.3.4.9 9H, Control 1, DOTAB, Tab 8 spaces 


The cursor is positioned to the right such that C contains a value divisible 
by 8. СИЯЯТ is called sufficient times so that this occurs. e.g. if Cel, 
CURRT is called 7 times after which C-8. 


6.3.4.10 AH, Contro] I, PLNFD, Cursor Down 


If in input return mode, CHRFLG set, then on return from EDIT the CRFLG is not 
reset and the line feed operation of Cursor Down is considered as occurring 
from the last line of the current line. If CHRFLG flag is not set, then the 
same processing occurs if B equals D. Otherwise B is just incremented and if 
the line feed would move into a continuation character C is incremented. 


When moving from the last line of a functional line into a new line, the HLOFLG 
is tested because if set the cursor cannot move out of the current line and 
routine returns. The value of D+LN+1 is computed and if equal to the depth, DEP, 
the routine returns, i.e. jams on the last line of the display buffer, but if 
CRFLG is set then whole screen scrolls. If D+LN+I is not equal to the depth, 
then this computed value is set as the new value of LN. 
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The new current line about to be entered is sized by counting the number of 
continuation characters and the number of characters on the last line. This 
results in the setting of D and E. 


6.3.4.11 BH, Control К, CURUP, Cursor Up 


Behaves inversely to Cursor Down. If B is zero on entry then moving up will 
enter à new line. This is sized to set D and E. If B is not zero then it is 
just decremented. If this results in it becoming zero then С is tested and if 
it contains ] it is decremented. The cursor is not allowed to move up into 

the prompt area and if this would result the cursor is positioned at the position 
immediately following the prompt. 


6.3.4.12 CH, Control L, HOME, Cursor Home 


BCDE are zeroised. The line that exists at the display buffer start is sized 
to set D and E. 


6.3.4.13 DH, Control M, NLINE. Newline 


Sets the end of line flags and returns such that CRFLG is not reset. CRFLG and 
CHRFLG are set and HLDFLG is cleared. В and C are zeroised and routine returns. 
ІҒ CRFLG was set on entry, as will occur if DH DH is passed to the EDITA, then 
the condition of INPFLG determines processing performed. 


-  INPFLG = 1, D and E are set into INPB and INPC 
B and C are set to zero 


-  INPFLG = Ø, the complete Tine following the line Newline'd 
out of is deleted. 
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6.3.4.14 EH, Control N, SHFTIN, Attribute On 


Sets SFTFLG which causes the bit 7 of all subsequent non-contro! codes to be 
inverted before displaying. 


6.3.4.15 FH, Control 0, SHFTOU, Attribute Off 

Clears SFTFLG set by SHFTIN in previous section. 

6.3.4.16 18H, Control P, NULL, Reserved for Graphics Escape 

At present does nothing, returns immediately. 

6.3.4.17 ТІН, Control 0, INSMOD, Enter Insert Mode 

Sets IFLG and returns. 

6.3.4.18 12H, Control R, MKPRM, Make New Line 

Makes the current physical line the first line of a functional line. This is a 
null operation if the cursor line is already a first line with B equal to zero. 
Effected by making B equal to Ø and C equal to 1 and performing a DELLT, section 
6.3.4.24, effectively deleting the continuation character. 

6.3.4.19 13H, Control S, MKSEL, Make Continuation Line 

Makes the current physical line a continuation line of the previous functional 


line. This is a null operation if the cursor line is already a continuation line 
i.e. if B not equal to zero. 
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6.3.4.20 148, Control Т, CCRET, Send Cursor Character 


If INPFLG is set then this control request is ignored. Otherwise, the SNDCCFLG 
is set which is intercepted by XIO and sends the character at cursor on a 
Subsequent call for input, section 5.4. 


6.3.4.21 15H, Contro! U, XYRET, Send Cursor x, y 


If INPFLG is set then this control request is ignored. Otherwise the SNDXYFLG 
is set which is interrupted by XIO and sends the x and y coordinates on 
Subsequent calls for input, section 5.4. 


6.3.4.22 16H, Control V, XYRQST, Set Cursor x, y 


If the HLDFLG is set then this contro]! request is ignored. Otherwise the 
XYFLG is set. The subsequent two characters passed to EDITA are expected to 
be cursor x, y coordinates, section 6.3.1. 


6.3.4.23 17H, Control W, TVRQST, Set ТҮ Control 


For video devices the TVMFLG is set. The subsequent character passed to EDITA 
is set in TVMDI, section 6.3.2. 


6.3.4.24 18H, Control X, DELLT, Delete Character to left of Cursor 


If the cursor is within or immediately to the right of the prompt area the routine 
returns immediately. For one line displays if the character to be deleted cannot 
be viewed since C equals WIN the routine returns without deleting. 


CURLT, section 6.3.4.8, is performed. The characters to the right and below the 
пен position of the cursor are shifted one position to the left. If this results 
in the last line of the current line becoming empty, lines lower in the display 
buffer are scrolled up one line. 


122 


26N0V81-VO-CRS NEWBRAIN-TECH-6.3 12.00 


6.3.4.25 19H, Control Y, DEL, Delete Character at Cursor 


An entry point within DELLT, this operates similarly but does not perform the 
Cursor left via CURLT. 


6.3.4.26 ЛАН, Control 2, CURRT, Cursor Right 

If C is less than LL then it incremented and routine returns. If B is greater 
than equal to D then neither B or C are incremented and cursor remains at line 
end. Otherwise B is incremented and C is set beyond the continuation character 
of the next line. 


6.3.4.27 1ВН, ESCAPE, ESCAPE, Escape next Character 


Sets the ESCFLG so that the next character passed to EDITA is set in the display 
buffer regardless of value. 


6.3.4.28 ICH, Contro! +, HOMEL, Cursor Home Left 

B and C are set to the first input position of the current line. For one line 
displays B and C are always set to zero; for other displays B and C are the 

values contained in INPB and INPC. 

6.3.4.29 1DH, Contro] +, HOMER, Cursor Home Right 

C is set to LL and B is set to D. 

6.3.4.30 ТЕН, Control HOME, DLINE, Delete Line 

Deletes the current line excluding the prompt. В and C are loaded from INPB and Ы 


INPC. If B is not equal to 0 then routine loops calling SCROLL with the Accumulator 
equal to D+LN each time deleting D. This deletes all lines below the cursor line. 
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WLIN is called which writes a zero at the cursor position and spaces to the 
remainder of the display line, which causes the hardware to stop making bus 
requests for remainder of the line. 


6.3.4.31 FH, Shift HOME, CLRSCR, Clear Page 


Calls Min for each display buffer line with C equal to zero. This sets a 0 
followed by LL-1 spaces in each line causing the hardware to stop making bus 
requests for remainder of the line. HOME, section 6.3.4.12, is called which 
zeroises B and C and sizes the first line in the buffer, which in this case is 
of zero length. 
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6.4 XEDIT ROUTINES 

This section contains routines which are either useful or demonstrate some 
Operations performed by XEDIT. Unless specified all routines expect BCDEHL 
to be in their display format and display own memory to be correctly defined. 
6.4.1 ADHLA, Add A to HL 

Function: HL = -a 

Preserves: BCDE 

6.4.2 BACAL, Calculate А times 0 

Function: ВС = A*D , D must be greater than zero on entry. 


Preserves: ЕН 


6.4.3 CALIN, Calculates display buffer offset to a location 
preceding a Tine of interest 


Entry: A = a display line number offset 9 


Function: ВС = EL*A 


Preserves: ADEHL 


6.4.4 ADLIN, Computes address іп display buffer of first 
тобот of а Tine 
Entry: А-а display line number offset 9 


Function: HL = HL+EL*A+ 


Preserves: ABCDE 
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Entry: 


Function: 


Preserves: 


6.4.6 


Entry: 


Function: 


Preserves: 


6.4.7 


Function: 


Preserves: 


ADLINI, Computes address in display buffer of location 
preceding a line 


А = a display line number offset , 
IL = HL+EL*A 
ABCDE 


GETDE, Computes the address one line оп 


HI 


points within the display buffer 


DE = HL on entry 
HL = DEEL 


GETCUR, Computes the address in the display buffer 
of the cursor 


HL = HL+EL*(LN4B) + Cel 
and A contains the character at this location 


BCDE 
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6.4.8 GETCR, Computes a cursor initial address 
Entry: А = а display line number offset f 


Function: HL = HL+EL*A+C+1 
and A contains the character at this location. 


Preserves: BCDE 


6.4.9 CPDB, Compares DE with BC 


Function: Carry set if within the current line 
Carry clear if beyond the current line 


Preserves: BCDEHL 
6.4.10 INCDE, increments DE 


Not a particularly useful routine but of interest demonstrating the type of 
operations that are performed by XEDIT which supports the one line and multi- 
line display types. This routine is called in INSERT prior to inserting the 
character into the display buffer at the cursor position. 


On entry the value of E is compared with LL. If less than LL, E is incremented 
and the routine returns. D is incremented and compared with the depth in DEP. 

If these values are the same then the current line has filled the display buffer. 
INPFLG is tested and if set the routine immediately returns and no more 
characters may be input if this full display buffer condition is reached. If 
INPFLG is zero, implying output mode then OLFLG is tested. For multi-line 
displays the output is allowed to continue though the display will scroll upwards. 
For one line displays the current output character is saved and a Newline 
Character passed to the EDITA through XIO. 
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On return the current output character is restored and Х10 is jumped into such 
that the Newline wait loop is entered, section 5.3.3, which waits for a Newline 
character to be entered before proceeding. 


When display buffer is not full but the current input line is full the routine 
ILIN is called. This uses a number of the routines described in previous sub- 


sections. One of two procedures may occur depending on the position of the 
just filled line. 
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If there are lines below this line then these are moved down and the last line 
in the buffer is lost. 


HL after ADLINI BC bytes in 
DF after GETDE X-1 lines 
from CALIN 


HL after GETOE 


On entry со ILIN, the Accumulator contains D+1+LN which is the line number, 
offset Ø, of the line to be vacated. X is calculated to be DEP-D«l«LN. With 
А-Х-1, CALIN computes BC-EL*(X-1). With A=DEP-1, ADLIN] is called which 
calculates the start address of the last line but one in the display buffer. 
GETDE puts this address in DE and the start address of the last line in HL. 

DE and HL are exchanged and an LDDR performed vacating the line following the 
current line. WLIN is called which writes a zero to the start location of the 
vacated line and 11-1 spaces following, thereby switching off the video hardware 
for the duration of that line. 


If the just filled line is the last line, i.e. X=, then a similar operation is 
performed which scrolls the last DEP-1 lines up the buffer thereby vacating the 
last line and losing the first. МІН is called as before. 

On return from ILIN the continuation character is set at the first location of the 
new line and E is set to 2. 
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74 INTRODUCTION 
The keyboard driver module supports two devices:- 

- KBWIO, keyboard wait for a key 

- КВІ10, keyboard immediate return with key if available. 
The two devices differ only on INPUT and share common OPEN, OUTPUT and CLOSE 
routines. No distinction is made between OPENIN and OPENOUT, either is 
allowed and opens the stream for input or output with an own memory allocation 


of one byte. 


The keyboard driver recovers a keyboard matrix coordinate from one of two 
routines dependent on the device:- 


- GETKEY, for K,, 
- IMMKEY, for KBIIO 


The returned keyboard key is converted into a value which is used to access the 
character ROM. The converted value may lie in the range 9H to FEH. 


9 - !FH Control Codes 
2) - ЗЕН ASCII numerics and symbols 


A 40 - БЕН ASCII upper case letters and symbols (Group A) 
а 5F - 7FH ASCII lower case letters and symbols 
- 8) - 7EH Graphics 
а А) - ВЕН Secondary Graphics 
CØ - DEH Tertiary Graphics 
14 Eg - РЕН Shifted Graphics 


The graphics are all derived from the Group A values as shown for the letter А. 
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The parameter KBMODE influences the returned character value. The least 
significant four bits of KBMODE are important:- 


Bits Value 


2 Shift lock, when set converts lower 
case alphas to upper case. 


1 Graphics shift 
2 Secondary Graphics select 
3 Tertiary Graphics select 


The routine KLOOK, section 7.7, which used KBMODE only tests Bit 3 if Bit 2 

is set, i.e. both must be set to obtain Tertiary Graphics. KBMODE is set up by 
RDKEY. When the control key and one of the numeric keys Ø to 9 is depressed, 
the corresponding bits of KBMODE are set as follows:- 


Mode Bits 3-0 of KBMODE KBMODE 


9202 90H 
0201 Фін 


о © зз ою ош э оо о ә 
= 
= 
е 
$ 
* 
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7.2 OPEN - KBOPI 


The open routine KBOPI is used by KBIIO and KBWIO. It calls MKBUFF with BC 
set to ]. The one byte of own memory is set to zero. BC is set to zero 
prior to return indicating a null length returned parameter string. 


134 


18N0V81-VO-CRS 


NEWBRAIN-TECH-7.3 01.00 


7.3 INPUT - KBIINP, KBWINP 


The two input routines differ only in the "get-key" call. KBIINP makes а 

call to IMMKEY which returns immediately with a keyboard key if one is ready, 
null if not; KBWINP calls GETKEY which waits until a keyboard key is depressed. 
Both IMMKEY and GETKEY are described in section 2.4. Prior to the appropriate 
call both routines swap the contents of own memory with the contents of the 
page zero location KBMODE. For KBIINP if no keyboard key is returned then the 
contents of KBMODE and own memory аге swapped back again and routine returns 
with zeroes in the accumulator. 


Otherwise, and always for KBWINP, the routine KLOOK is called, section 7.7 which 
converts the keyboard matrix coordinate returned by the "get-key" call into an 
ASCII or graphics character. 


On return from KLOOK the KBMODE contents and own memory are swapped back. If 
carry was set on return from KLOOK the the accumulator is cleared prior to return 
to 105. Otherwise the ASCII or graphics character is returned. 


18N0V81-VO-CRS NEWBRAIN-TECH-7.4 — 01.00: 


7.4 OUTPUT-KBOUT 


The function of the keyboard driver output routine is to set up own memory 
with the KBMODE shift status. Provide the value in the accumulator is in the 
range 0-9 then the contents of the accumulator are written to own memory. 

On input the contents of own memory are swapped with KBMODE; KBMODE is then 
read to determine shift and graphic lock status. 
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7.5 CLOSE-KBCLS 


Merely clears carry and returns. 
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7.6 ROKEY 
Entry: ROKEY 


Function: Waits for a valid keyboard key to be depressed and 
converts to an ASCII or graphics character. 


Routines: GETKEY section 2.4 
KLOOK Section 7.7 


Exit: A = character 
Carry is always clear 
BCDEHL preserved 
Params: KBMODE * 


The registers are preserved on the stack and GETKEY unconditionally called 
through the intercept mechanism. On return KLOOK is similarly called. Three 
exit conditions from KLOOK are considered:- 


- Carry clear, registers are reinstated and routine exits 


- Carry set and zero flag set, in this condition KLOOK returns 
HL pointing at page zero location KBMODE. The contents of 
the accumulator returned by KLOOK are written to the KBMODE 
location and routine loops back to GETKEY call. 


- Carry set and zero flag set, routine loops back to GETKEY 
call since keyboard keys depressed has requested an illegal 
graphics character. 
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7.7 KLOOK 
Entry: A = keyboard matrix coordinate 


Function: Convert keyboard matrix coordinate to ASCII or 
graphics character 


Routines: TTCAPS section 2.10 


Exit: Carry clear 
A = character 
Carry set and Zero Flag set = mode change request 
Carry set alone = invalid keyboard key combination 


Params: KBMODE 


The lower six bits of the keyboard matrix coordinate determine the keyboard key 
depressed, the upper two bits determine whether either the Shift, Control or 
Graphics key was depressed simultaneously. On entry to KLOOK the lower six bits 
are extracted by ANDing the accumulator contents with 3FH. If any of the top 
two bits were set on entry then 40H is added to this result. The resultant value 
is used to extract a character froma table, into the accumulator. The table 
contents are shown overleaf, 
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Bits Bits 6-4 
30 00 % оо оп 10 101 noo ш 
— 1 3 
0 m т н m m т 3 он өн 
1 oH н m т тн oH ГА т 
2 8s WT LF үт т 1н 2н 3H 
3 7 8 u j 9m | вн 0 ә 
4 6 9 i n 9 | em 1 N 
5 5 П y 95 | 90 Y м 
6 4 ( o à 94% L 2 ан 
2 3 ) i я өн 1 n ET 
8 2 * ; b om | sm | вн 8 
9 1 vo h v 9m m н Y 
А t р 9 c T 2 6 с 
8 r = f x R e F x 
с е - 4 z E N 2 2 
D “ s | ms м ^ 5 вн 
E 4 CR а к 0 эн А к 
F [| space | esc / ЕЕ M н | с ш 
N.B. Bit 6 set if any of Graphics, Shift or Control keys depressed 


First Conversion Look-Up Table 
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A particular group of characters, 8, A to 2, CN, J, A, are used to drive 
the four sets of graphics characters. This group of 31 original upper case 
characters is referred to as Group A. All other values extracted from the 
table above are not Group A. The subsequent processing is determined by the 
condition of the two shift bits, 7 and 6, of the accumulator on entry. The 
following states can exist:- 


Bits 7&6 Value 
әй Unshifted 
” Upper case shift key 
19 Сопїго1 кеу 
т Graphics key 


Note that if any of the shift bits are set then the value extracted from the 
table will be predominantly group A characters. The remaining values in the 
right hand four columns of the table are used as entries into sub-tables. 


7.7.1 Shift Bits = 99, Unshif ted 


Bit Й of KBMODE is examined. This is the shift lock bit. If set then a call 
is made to the OS routine TTCAPS, section 2.10, which will convert the value in 
the accumulator to its upper case equivalent provided it is one of the 26 lower 
case letters. Carry is cleared prior to returning. 
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7.7.2 Shift Bits = 01, Shift Key 


For group A characters the Graphics Shift Bit 1 of KBMODE is examined. If 
set then АЙН is added to the ASCII value of tne group А character in the 
accumulator to give the shifted graphics set of characters EUH to РЕН. The 
routine returns with carry clear. 


For non-group A characters, Bit 7 of the accumulator is reset and the resultant 
value indexes the sub-table overleaf extracting a character into the accumulator. 
Carry is cleared and routine returns. E.g. Shift 1 will give 91H from first 
table, resetting Bit 7 gives ТІН which indexes ":" from Sub-Table 1. 


143 


18NOV81-VO-CRS ___NEWBRAIN-TECH-7.7 05.00 

Value Character ASCII Effect 

0 RUBOUT 18H Delete left 

1 RUBRT 19H Delete character 
2 DL 2H Delete Line 

3 50 ЕН Attribute On 
4 < 

5 > 

6 

7 = 

8 п ІН Insert Line 
9 св DH Newline 

A Space 

B 51 FH Attribute Off 
с Т. 

D CLEAR ПЕН С1еаг раде 

t ( 

F ) 

10 сән 

n f 

12 , 

13 # 

14 5 

15 % 

16 & 

17 ғ 

18 ған 


Sub-Table 1 
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7.7.3 Shift Bits = 10, Control кеу 


For group A characters, 49H is subtracted from the ASCII value in the accumulator 
and routine returns with carry clear. 


For non group A if bit 7 of the accumulator is set then routine returns with 
carry and zero flag set. This feature is specifically used by RDKEY, section 
7.6, to set the KBMODE parameter in page zero. This condition only happens for 
the numeric keys when depressed concurrently with the control key. See the 
Introduction 7.1. for non group A characters which do not have bit 7 set then 
the value in the accumulator is used to index the table overleaf, returning with 
the extracted value in the accumulator and carry clear. 


E.g. Group A character W = ASCII 57H; subtract 40H gives 
17H which is Control W. 


Control. gives 5H from the first conversion table which indexes 
i from Sub-Table 2. 
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Value 


әзо>ос-чаольов- о 


Sub-Table 2 


Character 


CHL 
CHR 


Space 


Effect 


Cursor home left 
Cursor home right 


Set cursor x y 
Send Page 


Tab 8 spaces 


Clear Line 


146 


18N0V8l -VO-CRS  NENBRATN-TECH-7 


08. 00 


7.7.4 Shift Bits = 11, Graphics Key 


For group A characters, 40H is added to the ASCII value in the accumulator 
selecting the ordinary graphics. The KBMODE Bit 3 is tested. If set the 
secondary graphics are selected by adding a further 20H to the value in the 
accumulator. If Bit 4 of KBMODE is also set then another 20H is added to the 
accumulator selecting tertiary graphics. For each of these graphics selection 
the routine returns with carry clear. 


For non group A, if bit 7 of the accumulator is set then routine returns with 
carry set. If bit 7 is not set then the value in the accumulator indexes the 
table overleaf. The value extracted is set in the accumulator and routine 
returns with carry clear. 


e.g. Graphics. gives 5H from the first conversion table which indexes } from 
Sub-Table 3. 
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Value Character ASCII Effect 

0 oH 

1 gu 

2 © 138 Make continuation line 

3 MP 12H Make new line 

4 ( 

5 ) 

6 69H 

$ gH 

8 XYR 15H Send x, y 

9 19H 

A Space 

B 19H 

с 5 

n CCR 14H Send character at cursor 
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8.1 INTRODUCTION 
NEWIO is a collection of 4 drivers:- 


- LPIO, the line printer driver 
- 0610, general purpose bi-directional V24 driver 
- UPIO, user port driver 


- DUMMY, dummy interface to IOS. 


The first two operate similarly and utilise the same code. Both expect the 
port number passed by IOS in the D register to be zero. Both use bits in the 
Enable Register and User Port of Model A type Newbrains to effect data transfer. 


Signal Location Bit Use 
Clear to Send Printer User Port 7 Input from printer indicating 


when it goes low that printer 
is ready to receive a data 


byte. 
Transmit Data Printer Enable Register 7 Serial data output to printer. 
Clear to Send V24 User Port 1 Input from Ү24 device indicating 


when it goes Tow that device is 
ready to receive a data byte. 
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Signal 


Clear for Sendina 


Received Data V24 


Transmit Data V24 


Location 


Enable Register 


User Port 


Enable Register 


NEWBRAIN-TECH-8. 1 92.09 
Bit use 
4 Output to V24 device indicating 


that Newbrain is ready to receive 
a data byte. The immediate 
response from the device should 
be to set input stream to Mark 
state if not already. 


Serial data input from V24 
device. 


Serial data output to V24 
device. 


The serial data stream passing between the Newbrain and an external V24 type device 


is as follows:- 


Clear for Sending 


Data 


Mark Start 8 Data Bits 


? Stop 
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um 


8.2 LPIO 


The line printer driver is an output only device. Ne distinction is made 
between OPENIN and OPENOUT, either effectively performs an OPENOUT. Request 
code 2, INPUT, is not supported and if INPUT is attempted via IOS will result 
in an Illegal Request Code, Error 109. 


8.2.1 OPEN - LPOPOU 


The subroutine SOPN is called which analyses the open parameter string, calls 
MKBUFF and sets up own memory. The parameter string format for the line printer 
driver is:- 


[т [etes] [R ттт] 
where Т defines the start of the optional 
transmit field. 


ttttt is the transmit baud rate 
which is optional but must follow T. 


R defines the start of the optional 
receive field. 


rrrrr is the receive baud rate 
which is optional but must follow R. 


The parameter string is common for all software driven V24 devices. For the line 
printer only the transmit rate is used, the receive rate, should it exist, is 
ignored. The baud rate of the string ttttt and rrrrr are the actual baud rates 
of the attached devices, e.g. 2400, with a current design maximum of 19200 baud. 
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Prior to the analysis of “his string SOPN checks that the port number passed in 
D is zero. If not, error code 121 is set in the accuwulator - 111еда1 Port Number, 
and an immediate return is made to 105 with carry set. 


The length of the parameter string is checked not to be greater than 255, but if 
it is, error code 120, Baud Rate Parameter String Syntax Error, is set in the 
accumulator and a return made 10 105. Тһе first character of the string is 
converted to upper case via HLTTCAPS, section 2.19 of 05. If the first character 
is a "T" then the next characters are analysed and 1f these are numeric characters, 
converted to a sixteen bit binary integer. The result is divided into the maximum 
baud rate, 19200, to derive the baud rate parameter (brp) as a fraction of the 
maximum rate. E.g. if the actual device baud rate is 2400 which when divided into 
19200, gives 8, 8 is the brp parameter. 14 no numeric characters follow the T, or 
if no transmit field exists at all, then the default brp is 2, corresponding to a 
baud rate of 9600. The receive parameter is analysed similarily. 


BC is set to 4 and MKBUFF called. The four bytes of own memory are set up as 
follows:- 


Offset Value 


9 Receive Baud Rate Parameter 
1 Print Line Length set to 80 
2 Print Head Position initially set to 0 
3 Transmit Baud Rate Parameter 


On return from SOPN the last written byte to the Enable Register is retrieved from 
ENREGMAP. The IOPOWER Bit 3 and the Transmit Data to Printer Bit 7 are set into 


the byte, the result output to the Enable Register port with interrupts disabled. 
The registers В and С are cleared defining а zero length returned parameter string. 
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8.2.2 OUTPUT - LPOUT 

On entry HL points at start of own memory and this is incremented to retrieve 
the print line length. The output character in the accumulator is compared with 
the space character to determine whether it is a contro] cheracter. 


If it is not a control character then the current position of the print head, 
offset 2 of own memory is compared with the line length. 14 they are the same, 
à Carriage Return and a Line Feed character pair are output to the printer via 
LPWRT. The output character passed to the driver in the accumulator is then 
output by calling LPWRT. Unless any errors were detected by LPWRT, the Print 
Head Position parameter is incremented prior to a return to 105. 


If the character in the accumulator is а control character then one of tne 
following actions is performed:- 


- if it is a TAB character then eight spaces are output bringing the 
print head to a modulo 8 character position with a CRLF pair if the 
line length is exceeded. 

- if it is a Carriage Return this is output followed by Line Feed. 


- any other control character is passed directly to the printer. 


8.2.2.1 LPWRT 


BRKTST is called, section 2.7, which returns with carry set if the STOP key has 
been depressed; LPWRT returns immediately in this case. With interrupts disabled 
the User Port is input and the Clear to Send bit tested. The routine loops waiting 
for this bit to go low. 
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Тһе video, and thence the Bus Requests, is switched off via a call to NOVIJ 

in the Frame Interrupt Handler which resets the TVENA Bit 2 of the Enable Register. 
This is done so that the software delay loops in the following code of LPWRT 
generate accurate time intervals. With B set to 11 (1 start, 8 data and 2 top 
bits), C containing the output character and carry clear the outermost loop is 
entered. 


The data is passed to the output device via a bit within the Enable Register. 
The value of this bit is determined by the state of the carry flag on entry to 
the output loop. With carry set the bit is set, with carry clear the bit is 
clear. On first entry to the loop carry is cleared so that a start bit is out- 
put. With the output bit of the Enable Register set appropriately, the Enable 
Register port is written to. The routine then enters a delay loop, the number 
of iterations around which is determined by the transmit brp of own memory. 
E.g. if the brp = 1 equivalent to 19200 baud, the delay loop is not entered; 

if the brp = 2 the loop is performed once. 

A further delay is implemented and then the C register is rotated right one bit 
$0 that the next send bit is set in the carry while a one bit is set in bit 7 
of C. 


The loop is executed 8 (11) times, the ones fed into C are the stop bits once 
the 8 character bits have been output. The video is re-enabled by setting bit 4 
of TV2 which blanks TV after next Frame Interrupt but re-enables video by the 
interrupt after that. Interrupts are emibled, having been disabled for the 
duration of the cheracter transfer and with HL pointing at offset 2 of own 
memory and carry clear the routine returns to caller. 


8.2.3 CLOSE - UPOC 


The registers A, B and C are cleared. 
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8.3 4610 


This is a general purpose software driven V24 driver which operates through the 
Enable Register for output and the User Port for input. No distinction is made 
between OPENIN and OPENOUT, the same routine being called for each. Both INPUT 
and OUTPUT are supported. 


8.3.1 OPEN - JGOP 


Behaves similarly to LPOPOU section 8.2.1. SOPN is called which analyses the 
parameter string, calls MKBUFF and sets up own memory. Тһе IOPOWER Bit 3 and 
Transmit Data to V24 Bit 5 are set in the last written byte to the Enable Register 
which is then output to that port. B and C are cleared defining a zero length 
returned parameter string. 


8.3.2 INPUT - JGIN 


The TVENA and Clear for Sending bits of the Enable Register last written byte 
are reset and the resulting byte output to the Enable Register port. If not 
already at the Mark state, the input bit from the V24 device should go high in 
response to Clear for Sending going low. The routine waits in a loop until this 
bit, Bit 9 of the User Port, becomes high. DWAIT is called which waits for the 
input stream to go low indicating the start bit. This routine can wait for up to 
1 minute after which a timeout error 200 is set in the accumulator and with carry 
set returns to JGIN's caller normally IOS. 


Once the stop bit is achieved, the Clear for Sending bit of the Enable Register 
is set high. A delay loop is executed the Receive brp times. The 


input data is read through Bit 0 of the User port and the result shifted into the 


156 


1ØNOV81-VØ-CRS NEWBRAIN-TECH-8.3 02.00 


carry and thence into the E register where the input character is compiled. 
A fixed delay of 12 0042 instructions and a delay based on the Receive 

brp are perfomed so that on completion the next input bit from the 

V24 device will be ready at the User Port. 


The loop ends when the start bit is shifted throuoh the E register into the 
carry, at which time the E register will contain the eight data bits. Video 
is re-enabled as described in section 8.2.2.1 and interrupts enabled. Carry 
is cleared and the character in E is set in the accumulator for return to 105. 


8.3.3 OUTPUT - JGOUT 


Sets the V24 mark bits in D and E positions, the own memory pointer in HL at 
offset 2 and executes LPWRT, section 8.2.2.1. 


8.3.4 CLOSE- UPOC 


The registers A, B and C are cleared. Carry is not set. 
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8.4 UPIO 
The user port driver supports request codes 0-4 and performs the following:- 
- OPENOUT or OPENIN, clears A, B, C and Carry. 


- INPUT, inputs the 8 bit wide data from the port number 
passed in D from IOS to the accumulator. 


- OUTPUT, outputs the data in the accumulator to the port 
number specified in D. 


- CLOSE, clears A, B, C and Carry. 
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8.5 DUMMY 


Does nothing but provide a clear interface to 105 for request codes 0-4, 
for each code merely clears A, B, C and Carry. 
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9.1 INTRODUCTION 


Newbrain BASIC is an interactive compiler. Statements are entered from the 
console and as each line is entered a minimal lexical check is performed with 
BASIC reserved words converted into single byte representation. The compressed 
statement line is added to the Source Code area, its line number, set in the Line 
Number area which is maintained in numeric sequence. At execution time, the 
Source code is conditionally compiled into an intermediate object code saved in 
the Object Code area. The object code provides a set of pointers into a table 
of execute routines. As each statement is executed, the compilation phase is 
only performed if the object code does not exist. 


BASIC is an example of a user program which exists in high RAM but addresses 

the full random access memory through accesses to page zero variables, stack 
usage, the floating point memory through calls to the Maths Pack, and 105 memory 
when it performs 10. It calls OS, IOS and Maths Pack routines via the intercept 
mechanism, picking up routine addresses from ZOSTABLE. 145 own internal routines 
are called directly or via the intercepts through RSTI6 and RST24 which call BASIC 
routines through ZTABLE. 
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The RAM organisation is:- 


B3PRM 


B4 


low address 


Fixed Locations 


Source Code 


Area 


Object Code 


Area 


User Stack 


FOR Block area 


GOSUB Stack 


Arrays 


Symbol Table 


Line-Number 
Table 


High address 


Section 

IY 

9.1 
lY + 6! 

9.2.1 
STOP 

9.2.3 
ОТОР 
SRS Ip 

9.2.4.6 
FORPTR 

9.2.4.5 
GSSPTR 

9.2.4.4 
5ТВА5 

9.2.4.3 
ARBAS 

9.2.4.2 
SBAS 

9.2.4.1 
LBAS 

9:2:1 
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The fixed locations аге:- 


Displacement from IY 


0 


Length Name 
6 
1 олсок 
1 INCON 
1 ERRNO 
2 INPTR 
1 
2 SVINPT 
2 STOP 
2 ОТОР 
г USRSTP 
2 FORPTR 
2 GSSPTR 
2 STBAS 


NEWBRAIN-TECH-9.1 03.00 


Value 


Unused 


The 10S stream to which output is 
currently being made. 


The IOS stream from which input is 
currently being taken. 

GET and PUT use displacements 6 & 7 
in a special way. Stream f is used 
by BASIC as the console. 


The number of the last error or 
interrupt to have occurred in 
program execution. 


The position from which RDCH and 
other input routines are taking 
input from stored text. 


Unused. 

A location for saving INPTR. 
Points to top of source code. 
Points to top of object code. 
Base of user stack. 

Base of the FOR blocks area. 
Base of the GOSUB stack. 


Base of the String area. 
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Displacement from IY 


26 


?8 


30 


32 


34 


35 


37 


Length 


2 


Name 


ABA 


5ВА5 


LBAS 


ТОР 


FLAGS 


NCONNO 


SCONNO 


NEWBRAIN-TECH-9.1 04.00 


Value 

Base of the Array area 

Base of the Symbol Table 
Base of the Line Number Table 


Top of the BASIC RAM area which can 
be moved down with the RESERVE 
command 

Bit f set during execution used by 
INITOB inhibits deletion of curr '* 
object code line. 

Bit 1 set if interrupts are to be 
ignored: 

Bit 2 set if tokens are not to be 
expanded during listing (e.g. during 
SAVE) 


Bit 3 set during compilation used by 
INITOB inhibits deletion of object 
code line. 

Bit 4 is set whilst compiling a DEF 


so VARIAB can watch for formal 
parameter occurrences 

Bit 5 is set if compilation is not 
to produce object code 


Count of number of numeric constants 
encountered to give each one a 
unique name type. Not currently 
implemented. 

Count of number of string constants 


encountered. Bit 14 is always set. 
Not currently implemented. 
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Displacement from IY 


39 


42 


43 


44 


46 


47 


49 


51 


53 


55 


Length 
3 


OTYPE 


PPFLGS 


DTINPT 


DTLN 


FORVAR 


APAR 


FPAR 


Value 


Holds the line number and displacement 
where last break of execution occurred. 


Bit Ø = base of arrays either f or 1 
Bit 7 = lower base is now fixed if set 
Set by DIM statement or OPTION BASE 
statement. 


Temporary variable for EXPN, the 
expression compiler. Set to f if а 
numeric expression found or 19H if 
string expression. 


The amount by which the object code 
has moved during execution of a line 
always negative usually zero. 


Used by AMENDL and XLIST, indicates 
state during entokening source line. 


Like INPTR but used for reading DATA 
statements. Only one byte is used. 


The current line number that the DATA 
pointer is on. Changes to the Line 
Number table entry during execution of 
a READ. 


Temporary variable during compilation 
of a FOR statement. 


Absolute pointer into the user stack 
of the actual parameter being 
evaluated in a User Defined Function. 


Holds the name type of the parameter 
being evaluated in a User Defined 
Function. 
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Displacement from IY 


57 


59 


Length 


2 


2 


Name 


ERRLIN 


BRKLIN 


Value 


Where control is passed to if program 
error. If no trap exists then it is 
zeroised. 


Where control is passed if a break 
occurs. If no trap exists then it is 
zeroised. 
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9.2 BASIC Main Loop 


The entry point to BASIC is the label BASIC and is the default value set in 

the page zero location UP by OS during the power up sequence, section 2.2. 

The BASIC program initialises itself and opens the console and uses DEVA as device 
number, DPSP and DPSL as the parameter string and zero as the port number and then 
enters a loop which will either be a statement or a command, the latter indicated by 
the absence of a line number, 


9.2.1 Statements 


The routine AMENDL performs the initial processing of statements. Each BASIC 
Statement can be considered composed of:- 


- à line number 
- an initial keyword and parameters 
ж other keywords and parameters. 


The keywords are each converted into single byte tokens. А cross reference 
list of keywords and tokens is held in the table KWDLIS. The single byte tokens 
have bit 7 set and therefore are in the range 128 to 255. There are two sets of 
tokens; one set refers to initial keywords, the second set to other keywords. 
Tokens in the two sets may have the same value but a different meaning. For 
example, token value 128 is equivalent to LET as an initial keyword and NOT if 
it is another keyword. All keywords, functions, operators and BASIC connective 
words (THEN, TO, STEP, etc) have a corresponding token. Some have two. ? and 
PRINT mean the same thing but are assigned two different tokens so that on 
Conversion back to the full BASIC form when LISTing the program, the statements 
are reproduced as entered. AMENDL also performs a minimal syntax check 
specifically to identify IF THEN statements. Newbrain BASIC does not normally 
Tequire the THEN to be inserted e.g. IF X-Y LET A-B. The BASIC compiler however 
cannot handle implied THENs so AMENDL inserts an "invisible" THEN token at the 
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correct location within the statement. 


The entokened statement, which is shorter than the input source statement , 

is added to the top of the Source Code Area, STOP. All source lines of the 
program and any command line are held here. When old lines are deleted the 
others are moved down. Each one ends in a Carriage Return which replaces the : 
in multi-statement lines which are split in the Source Area. The ordering of 
the source lines is not significant, program statement sequence being maintained 
in the Line Number table. The statement line number is inserted into the Line 
Number table in correct numeric sequence. А line number table entry has the 
format:- 


Offset Length Contents 
2 2 Тһе line number 
2 2 Pointer to first character of a 
statement in the Source Code Area 
4 2 Pointer to the Object Code 


At this tage the Object Code pointer does not exist and is set to zero. The 
entries are always held in line number order, low numbered lines having low 
addresses. —Multi-statement lines have a separate entry for each statement, 
each having the same line number, and are held in the correct textual order. 


9.2.2 Commands 


If the input string from the keyboard is interpreted as a command it is handled 
by the routine COMMAN. This assigns a line number of 9 and calls AMENDL which 
entokens the line and sets an entry, or entries, at the low address end of the 
Line Number table. 
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9.2.3 Compilation 


BASIC executes a program by calling EXEC. This operates by inspecting the Line 
Number table. EXEC can determine the sequence that statements are to be 
executed and the address of the object code. On first pass through, the object 
code pointers will be zero indicating that the corresponding source statement 
has not been compiled. EXEC calls CMOBJ which compiles a statement. 


The tokenised statement in the Source is analysed, the syntactic position of 

each token determines whether it is an initial keyword token or another 

keyword token. For each initial token there is a corresponding Compile module, 
the module name prefixed with the letter C. Other syntactic objects may have 
corresponding C modules e.g. CLABEL is the compile routine for syntactic 

Object line number. Тһе appropriate C routine for a token is effected 

by the routine STATEL. This is called via ZTABLE and may therefore be intercepted, 
see section 2.6. 


The output from the compile modules for a statement is an object code record 

composed of Y-codes and parameters. Y-codes are one byte operators, which currently may 
have Ø, 1 or 2 parameters. At execution time the compiled sequence of Y-codes 

results in a sequence of calls to a corresponding set of execute routines 

prefixed with the letter X. The Y-code is an index into the table XTABLE which 
provides the address of the corresponding X routine. 


The compiled object code line is set at the top of the Object Code Area, OTOP. 
Each line is preceded by a two byte count giving the total length of the object 
code record. The address of the first byte of object code after the count is 
set in the Line Number table. 
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9.2.4 Execution 


EXEC extracts the object code pointer from a Line Number table entry. The X 
routines are determined and executed by XCL3. Normally statements are only compiled 
once on first pass through the program with the result that execution is very 
efficient. Occasionally, for example when free memory becomes exhausted, 

the object code is deleted, and the object code pointers in the Line Number 

table set to zero. As subsequent statements are executed they will require to 

be compiled. No significant overhead is caused by this unless there is very 

little free memory. Since the object code consists of pointers into both the 

Symbol and Line Number tables which are fixed during execution, instructions 


that alter them (e.g. DELETE, RESERVE, CLEAR, MERGE) also cause the object code 
to be deleted. 1X is used during execution as the Line Number Table pointer and ~ 


behaves like a program counter. 


At execution time a number of tables are used:- 


- Symbol Table 
- Array Area 

- String Area 

-  GOSUB Stack 

- FOR block area 
- User Stack 


These tables expand towards lower memory addresses with for any particular entry 
offset Ø at the low memory end of the entry. Тһе RUN command initialises all 
tables so that all base addresses are concurrent with LBAS. 
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9.2.4.1 Symbol Table 


Symbols and constants are added to the base of the table (SBAS) as they are 
encountered which preserves the validity of the absolute pointers іп the object 
code. Deletion of symbols is by the CLEAR statement. Entries may be selectively 
removed by CLEAR, remaining entries are moved up destroying the integrity of 
Object code pointers, necessitating the deletion of the object code. Al 

symbols are 8 bytes in length. The first two bytes contain the name type 


For a variable, the low order 10 bits is a coding of the variable, which 
is 


37% (First letter) +С 


where First letter is the first letter of the 
variable mapped into the range 0-25 e.g. A=. 
C=36 if no second character 
or С-26 + digit if digit is the second character 
оғ С is the second letter of the variable mapped 
into the range 0-25 
e.g. variable B7 is coded as 
37*1 + 2647 


For a numeric constant the name type is fH, for a string constant agp and the 
system variable FILES, which contains the last retrieved parameter string from 


105, has a special name type that cannot occur for constants or variables. 


The remaining bits of the name type bytes are used as follows:- 
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Value 


Unused 

1 = user defined function, # otherwise 

1 = 1 dimensional array or if a user defined function, 
bit 11 set, then function has a numeric parameter 

1 = 2 dimensional array or if a user defined function 
bit 11 set, then function has a string parameter 

1 = string constant, string array, string variable 

or if a user defined function with a string result 

9 = constant, 1 otherwise. 


For an array, if both bits 12 and 13 are set, this means that it is not certain 
yet what number of dimensions the array has. For a user defined function if 
neither bits 12 and 13 are set the function has no parameters. 


The other 6 bytes are used as follows:- 


= numeric variable or constant, the floating point value of 
the constant or current value of the variable. 


- string variable or constant 


Offset 
2 
4 
6 


- arrays 


Offset 
2 

2 4 
6 


Contents 

Position in String Area relative to ARBAS 
Length of String 

Unused 


Contents 

Position of Array relative to SBAS 

15% Dimension 

2nd Dimension, or 2 if 1 dimensional array 


- user defined function, the six bytes are unused. 
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9.2.4.2 Array Area 


Contains the elements of arrays. The start address of the first element of an 
array is contained in the Symbol Table entry for the array name. The Symbol 
Table entry specifies the array start as an offset from SBAS since SBAS may 
move as symbols are added or deleted. When array are deleted by CLEARing the 
array name the offsets of all the arrays in the symbol table are updated. 


The elements of an array are held as six byte entries in the Array Area. For 
numeric arrays the six bytes contain the current floating point value of the 
array element. For string arrays the six bytes are used in the same way а5 the 
last six bytes in the Symbol Table. 


Offset Contents 
? Position in String Area relative to ARBAS 
E Length of String 
4 Unused 


Low numbered elements live in low memory addresses. For two dimensional arrays 
the elements are ordered (0, 2), (0, 1),....(1, 0), (1, 1), (1,2) etc. The 
offset of an element relative to offset 2 of the array is:- 


((ist subscript) * (2nd Dimension) + (2nd subscript)) * 6 
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9,2.4.3 String Area 


The String Area contains only the actual strings which are in no particular 
order. As strings are modified, extended or shortened, they are repositioned 
to the base of the string array area STBAS, with the vacated space closed up. 
Consequently, string pointers in the Symbol Table and Array Area have to be 
updated. Pointers into the String Area are relative to ARBAS as the contents 
of the Symbol Table and Array Area may change. 
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9.2.4.4 GOSUB Stack 


This consists of 3 byte entries containing the Line Number table entry addresses 
of the GOSUB statements that have yet to be RETURNed from, the most recent 

are at the lower addresses. Three bytes are used so that when in command mode 
the current position in a multi-statement line may be determined absolutely. 

In these circumstances the first two bytes are the actual line number and the 
third byte is the statement number in the current line with first statement 
being l. 
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9.2.4.5 FOR Block Area 


A FOR Block is twenty bytes of the following format: 


Offset 


Rowe 


Length 


o o оо 


Value 


Line Number table entry of NEXT statement 
Line Number table entry of FOR statement 
Floating point value of STEP factor 
Floating point value of TO limit 

Symbol Table entry of FOR variable 


The line number entries use three bytes as for the GOSUB stack. 
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9.2.4.6 User Stack 


This stack is used by the object code interpreter when a Y-code demands a push 
or pop. FOR blocks grow initially out of the user stack and get taken over by 
FORPTR. The stack is used for passing actual parameters and link information 
in User Defined Function execution. The stack is also used as the RDLINE input 
buffer. At times INPTR and SVINPT, when amendments are taking place in lower 
memory, and if pointing to an input buffer or the user stack, then these will 
be relative to the user stack rather than absolute addresses. 
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9.3 META-MODULES 
The groups of modules which support the BASIC interpreter operation are: 


- Compile Routines 

- Atomic Compilation Routines 
- Symbol Table module 

=- X Routines 

- Input Stream module 

~ Output Stream module 

= Working Store Manipulations 


9.3.1 Compile Routines 


The source statement token is used by STATEL to extract the corresponding C 
routine. Each initial keyword token has a corresponding compile routine e.g. 
TGOTO corresponds to CGOTO. Other keyword tokens do not always have a 
Corresponding C routine whilst certain syntactic structures, such as the line 
number argument following a GOTO, have a C routine in this case CLABEL. Included 
іп these modules is the expression compiler. 


The statement LET C = A + B * 2 would be compiled into the following:- 


YPUSH2 « symbol table address С> 

YPUSH2 < symbol table address А > YDEREF 

YPUSH2 «symbol table address 8 > YDEREF 

YNCONST < symbol table address "2" > ҮТІМЕ5 YPLUS YLEN 


Variables are compiled using VARIAB and may require an addition to the Symbol 
Table via the Symbol Table metamodule. 
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9.3.2 Atomic Compilation Routines 

As object Y-codes are created they are passed through CMONE to be put into the 
Object code area. This is interceptable through 05 if the object code is to 
be stored somewhere else. Includes the useful routines:- 


- CREM, compiles ҮНЕМ which at execute time is а No-op 


- СРН, compiles YPUSH2, 9. D, puts two zeroes on the 
user stack at execution time 


-  CPSH, compiles YPUSH2 which push the following two 
bytes in the object code record onto the user stack 


-  CMTHRE, compiles codes in order А, L, Н where A might 
contain a Y code and HL a pointer(A,L.H are 789 registers) 


-  CM2HL, compiles codes in order L, Н 


=-  CMONE, compiles codes іп A which might be a Y-code or 
argument. 


A flag may be set to inhibit the generation of object code, Bits of IY+FLAGS 


9.3.3 Symbol Table Modules 


Performs the creation and deletion of symbols for arrays, string, variables, 
constants and user defined functions. 
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9.3.4 Х Routines 


Called by corresponding Y-code performs stack operations оп strings numbers and 
arrays. 


9.3.5 Input Stream Module 


Provides BASIC with an internal read from stored text either read into a buffer 
via OS or internally. RDLINE is the main input routine and reads a line of 
input from stream E onto the user stack. The input line is always expected 

to end with a Carriage Return. 


9.3.6 Output Stream Module 


Outputs direct to the current output stream in OUTCON. Included are routines 
to: 
- PTCH, write a character 
- PIMSG, write a message. This is used to output an in-code 
message and is used а5:- 
CALL PN 
DEFB byte count» 
ПЕРМ "«message»" 
= PTNL, write NEWLINE, outputs a single (DH character 
- PTEOF, write End of File mark, two characters 94H, ФОН 


9.3.7 Working Store-Manipulations 
Manages memory storage for BASIC:- 


- adding and deleting entries from tables 
- MKSPC and RETSPC routines. 
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10.1 INTRODUCTION 


Floating point numbers are stored as 6 bytes with an internal range of 
110150. this internal format has a precision in excess of 10 significant 
digits and all calculations are carried out to the full precision. The 
floating point algorithms have been designed to minimise cumulative rounding 
errors and maintain stability in interative calculation. Numbers output in 
ASCII from the maths pack may only be in the range 210299. Output less 

than 10799 is set to zero, output greater than 10799 
error. This error is not signalled in the carry flag - instead ****'s are 
output in the appropriate field width. In formats other than free format 
underflow сап be an error and ....'s are output. All other errors detected 
cause the carry flag to be set on return but no error number is set in the 
Accumulator. 


results in an overflow 


The Maths Pack has 160 bytes of memory reserved for fts use starting at 
address 1008. The first six bytes of this memory is the floating point 
accumulator FACC which is used to pass operands between the calling user 
Program and the Maths Pack. Although the entire Maths Pack memory may be 
used by any particular floating point routine, between calls only locations 
137H to 13AH (which contain the random number seed) must be preserved if 
being used. The remaining memory is available for use and so in theory the 
stack area may grow down into the Maths Pack memory beyond the allocated 
memory provided these rules for avoiding conflicts are adhered to. 
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10.2 ROUTINES 


Maths Pack Routines can be categorised into:- 


= zero argument routines 
- single argument routines 
- double argument routines 
- special routines 


10.2.1. Zero Argument Routines 
Exit: Answer in FACC 


HL points to FACC 
ABCDE destroyed 
Carry always clear 


Functions: PL: the trigonometrical constant TT 
ЕРОКЕ the floating point number 
FPZERO the floating point number 0 
FPMONE. the floating point number -1 


RND a pseudo random number from the uniform 


distribution 0-1 


STPOS returns "PEEK" of print head position from page zero 


location РНР05 
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10.2.2 


Entry: 


Exit: 


Functions: 


Single Argument Routines 


Argument in FACC 


Answer in FACC 

HL points to FACC 

Carry set only if an error 
ABCDE destroyed 


NOT 


NEG 
ABS 
INT 
SIGN 
SQRT 
SIN 
cos 
TAN 
ASIN 
ACOS 
ATAN 


LOG 
EXP 
NOP 
PEEK 


Boolean operation - numbers are truncated to integers in 
the range -32, 768 to +32, 767. If this cannot be done 
an error will be returned. A bitwise binary operation 
is then performed and the result floated to provide the 
the answer. 


Negate 

Absolute value 

Integer part (greatest integer c) 

Sign (returns - 1,0 or 1) 

Square root 

Trigonometric function 

Trigonometric function 

Trigonometric function 

Inverse Trigonometric Function(-Y/2, Y/2) 
Inverse Trigonometric Function (0, T) 
Inverse Trigonometric Function (/e, Y/2) 


Natural logarithm 

Exponential functions 

Unary Plus 

Fixes the address in FACC and access the resulting 16 bit 
address. The byte recovered is floated into the Floating 
Point Accumulator. 
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10.2.3 Double Argument Routines 
Entry: Arg 1 in FACC 


DE points to low address of Arg 2 


Exit: Answer in FACC 
HL points to FACC 
Carry set if error 
ABCDE destroyed 


Functions: AND see NOT section 10.2.2 
OR ditto 
MULT Multiply 
DIV Divide Arg 1 - Arg 2 
ADD Add 
SUB Subtract Arg 1 - Arg 2 
RAISE Exponentiation (Arg 1) Arg 2 
NUMGE Greater than or equal 
NUMNE Not equal 


NUMGT Greater than Compares Arg 1 with Arg 2 
NUMLT Less than Result is -1 if true 
NUMEQ Equal @ if false 
NUMLE Less than or equal e.g. NUMLE gives true if 


FACC < (DE) 
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10.2.4. 


10.2.4.1 


Entry: 


Exit: 


10.2.4.2 


Entry: 


Exit: 


10.2.4.3 


Entry: 


Exit: 


10.2.4.4 


Entry: 


Exit: 


Special Routines 


LDF Load the Floating Point Accumulator 


HL points to operand 


HLBC preserved 
ADE destroyed 


STF Store the Floating Point Accumulator 


HL points to destination 


HLBC preserved 
ADE destroyed 


FIX Convert to 16 Bit Positive Binary 


FLT 


HL points to operand 


DE - answer 

ABCHL destroyed 
FPACC destroyed 
Carry set if overflow 


Convert 16 Bit Positive Binary Floating Point 
DE - operand 
FACC = answer 


HL points to FACC 
ABCDE destroyed 
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10.2.4.5 СОМР Сотраге 


Entry: HL points to first operand 
DE points to second operand 


Exit: Carry is set if first operand greater than second clear 
otherwise 
Zero flag set if operands are equal 


10.2.4.6 INP Convert ASCII to Floating Point 
Entry: DE points to first character of string 


Exit: FACC = answer 
HL points to FACC 
DE points to first unused character in string 
ABC destroyed 
Carry set if input number too large 


GIJ (digit® С. Big J t.digit*) СЕ Gil digit [digi] 


where L. ] indicates an optional field 
( ) indicates mandatory field 
І indicates "ог" 
digit is ASCII character in range "9" to "9" 
* — indicates may be repeated 
E is ASCII character "E" or "e" 


Spaces are disregarded 
The * or - characters may be ASCII or the NewBrain BASIC 
token * or -. 
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Entry: 


Exit: 


OUT, Convert Floating Point to ASCII 


Number іп ҒАСС 
BC = format code 


HL points to output string 

C = number of characters in string 
ABCDE destroyed 

Carry always clear 


Format Coding: 


bits 6,7 of B = format code, Ғ 
bits 0-5 of В = integer digit count, i 
с = total digit count, t 


Fixed point format 

Number is rounded to decimal with t 
digits, t-i decimal places. Leading 
zeroes represented as spaces, 1 leading 
space or minus sign, 1 trailing space. 
Total field width t + 3, except when 

t = i (integer format), t + 2. 


Free format 

Number is rounded to t significant figures ап: output 
in fixed or exponential format - goes to 

exponential above 10° or below 1073, 

Underflows are converted to ASCII 2. 

The field width is variable. 
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Ға: Exponential format 
Number is output as fixed point format with two digit 
exponent a multiple of i field with t + 7. 

For all formats must have 10%t >i >@. 


The answer is returned as an ASCII string in the Maths Pack memory area. 
Maximum string length is 17 characters. The string may become invalid after 
subsequent calls to routines which use the Maths Pack memory area. No errors 
are returned but attempting to fit number into inappropriate formats will 
result in the output string containing asterisks on overflow or periods on 
underflow, 


10.2.4.8 RANDOM 


Function: The "RANDOMIZE" function seeds the random number generator 
the value of page zero location CLOCK. 


10.2.4.9 INITRAND 

Function: Seeds the random number generator with a standard value. 
10.2.4.10 ROUND 16 Bit Positive Binary of (FACC) * 0.5 (as FIX) 
Entry: HL points to operand 

Exit: DE - answer 


ABCHL destroyed 
Carry set if overflow 
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10.2.4.11 MATHS, interface to Ø, 1 and 2 argument maths routines. 
Entry: А = 1 byte routine code 


HL points to 0, 6 byte or 12 bytes data area. 
The Maths Pack routines may be called through the general interface routine MATHS. 
This picks up entry addresses from the 05 intercept table ZOSTABLE. Three sub-tables 
exist within ZOSTABLE. 

- ARQTAB, the list of @ argument routines 

- ARITAB, the list of | argument routines 

- AR2TAB, the list of 2 argument routines 
The special floating point routines are not accessible through this interface. The 
Accumulator contains an entry code,bits 7 and 6 determine the sub-table, bits 5 to 
9 determine the offset of the required routine within the sub-table. The bits 7 
and 6 selection are: 

- neither set selects АЯЙТАВ 

- bit 7 set selects ARITAB 


- bit 6 set selects АВТАВ 


HL on entry points to a data area which contains ] or 2 operand data. 
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АЛ HARDWARE PORT ALLOCATION 
Port Ø, CLUSR, Clear User Interrupt, read/write. 
- No data transfer is associated with port 9. А read or write 
causes the interface signal CLUSR, Clear User, to be strobed. 
The interface signal USRINT should be reset. 
Port 1, ENRGZ, Load 2nd Enable Register, write 
- The 2nd Enable Register is not currently defined. 
Port 2, PR, Load Page Register, write 
ы Available in Model M machine only. Causes an 8k memory module 
to be paged into the 780 address space. The page address and 
memory module are specified as follows:- 


Bits Value 


0-6 Memory module identifier 
ROM/RAM identifier. 


Additionally А13, А14, А15 of the address bus are set to the 
180 address space page number. А8-А12 are undefined. 


Port 3, USER, Load User Output Port, write 


+ A byte of даға is written to the user port latch. Тһе signal 
USTRE is strobed. 
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Port 4, CECEK, Clear Clock Interrupt, read/write 


= No data transfer is associated with port 4. A read or 
write causes the CLCCK to be strobed which clears the 
clock interrupt. Interrupts only reach the 280 if the 
corresponding enable is set. In this case the TITIR 
Signal need only be activated if the clock enable has 
been set via the Ist enable register. 


Port 5, TEOMA, Clear DMA Interrupt, read/write 


- Not currently implenented but will behave similarly to the 
port 4 Clear Clock Interrupt. 


Port 6, COP, Address COP's chip, read/write 
- Тһе СОР 1/0 Port. 
Port 7, ENRGT, Load Ist Enable Register, write 


A data byte is written to the Ist Enable Register. Two 
principle byte formats exist. For the Model A this is:- 


Bit Value 


Clock FnabTe 

Not Used 

тү Enable 

Not Used 
Clear Tor Sending У24 
Transmit Data V24 
Not Used 

Transmit Data Printer 


2 эш юз ә 
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For Newbrain the Enable Register format is:- 
Bit Value 


Crock Enable, enable clock interrupts 

User Enable, enable user interrupts 

TV Enable, enable video 

V24 Enable, synonymous with V3 power enabled 
V24 Select Receive Bit 0 

V24 Select Receive Bit 1 

ves Select Transmit Bit 9 

V24 Select Transmit Bit 1 


ч оо ш оэ ош ә эъ 


The Bits 5 and 4 select one of four V24 inputs as follows:- 


Bits 5, 4 Selection 


” Tape Loop 0 
n Tape Loop 1 
19 Unassigned 
n Serial Communications 


Similarly Bits 7 and 6 select one of four V24 outputs as follows:- 


Bits 7, 6 Selection 


0% Tape Loop @ 
” Таре [оор 1 
19 Printer 


n Serial Communications 
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For Model V, bits 0 and 2 of the Ist Enable Register are not used since there is 
no TV and therefore no clock requirement. Bit 3 is not used as V24 is permanently 
disabled. Also for Model V only the Printer and Serial Communications of the four 
possible V24 directions reach an 1/0 connector. 


Additionally, for all models, bits 5 and 4 of the Ist Enable Register select one 
of four directions for Bit Ø of the Status Register, port 20; bits 7 and 6 
likewise select one of four directions for Bit 1 of the Status Register. 


Ports 8 & 9, ТҮС, Load TV Addresses, write 


- The Тү RAM character buffer starts on а 64 byte boundary іп 
the memory address range 0-32k. Under these conditions this 
start address пау be specified іп 9 bits. The address bits 
А7-А14 are specified through port 9. No data is transferred 
through port 8 but, the act of writing to port 8 causes the 
bit 6 of the TV RAM start address to be set. The load TV 
address is performed each frame, the hardware resets bit 6 of 
the start address at frame end. 


Ports 10 & 11, are undecoded and appear as ports 8 & 9. 
Port 12, ТҮСТЕ, Load TV Control Register, write 
A data byte is written to the TV Control Register and controls 
the access and display of data from the character ROM. Two 


full 256 character sets are stored. The TV Control Register bit 
assignments are:- 
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Bit Value 
? Reverse Video 
1 1 = Full set of 256 characters 


@ = first 128 characters with bit 7 of 
character address as an attribute 
2 For model M specifies a 2nd set of 128 characters 
3 UCR, upper character ROM, selects second 
character set and also selects 8TV lines 
per character (standard is 10) giving 30 
character lines per screen. 


4,5 ‘Unused. 
@ = 40 characters per line, 1 = 80 characters per line. 
7 Unused. 


Ports 13, 14 & 15 are undecoded and appear as port 12. 
Ports 16, 17, 18 and 19 are reserved for Read Analogue Data. 
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Port 20, UST, Read Status, read 


Bits 


A byte of data is read from the status register. Three types 


of information are returned:- 


1) The interrupting device in the event of an interrupt 


2) Hardware statuses 


3) 044 input signals e.g. calling indicator, user status. 


The condition of bits 0 and 1 are determined by the condition of 
bits 4-7 of a previously written Enable Register, port 7. 


Value 


CALLIND, Calling Indicator 
tape in, the digitised audio 
output from the cassette 


1-40 characters per TV line 
0-80 characters per ТҮ line 


1=ехсеѕѕ of 24 
B-excess of 4 


TALLIND, Calling Indicator 


BEE, if set then processor 
15 Model A type 


TVCNSL, if set then processor 
has video device as primary 
console output. 


Enable Register Bits 7 А 6 


n 
10 


01 


00 


Enable Register Bits 5 & 4 


n 


10 


ol 
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Port 21, 


Port 22, 


Value 


PWRUP if set indicates that power 00 
is supplied to 780 and memory 


Mains Present, indicates for battery 
backup models that, high consumption 
circuitry may be activated. 

User Status 


User Int, when set indicates an interrupt from the user device 


CTock fnt, when set indicates an interrupt from the 20mS video 
clock 


АСТА Tnt, when set indicates an interrupt from the АСТА 
СОР Int, when set indicates an interrupt from the COP 
» User Input for Newbrain and Model V, read 


- Reads a byte of data from the user port for the specificed 
processor models. 


„ User Input for Model A, read 


- Supplies input signals for software driven minimal V24 interface 
and a route for tape in signal 
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port 23, 


port 24, 


port 25, 


port 26, 


port 28. 


Bit Value 
0 Received Data V24 
1 Clear to send Ү24 
2-4 Not Used 
5 Tape in, the digitised audio output from 
cassette 
6 Not Used 
7 CTear to Send Printer 


undecoded and appears as port 21. 
ACIA Control/Status Registers, read/write 


- A read from port 24 returns the 6850 status register. 
A write to port 24 loads the 6850 control register. 


» ACIA Transmit/Receive Registers, read/write 


K read from port 25 returns the 6850 data out 
-  Awrite to port 25 loads the 6850 data input register 


27, Unused. 
» CTC Channel 9, read/write 
» A write to port 28 loads the 280 CTC with a timing or counter 
value. Connected to the ACIA Receive Clock this port is 


usually used in counter mode 


- A read from port 28 returns the counter constant. 
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Port 29, „ CTC Channel 1, read/write 
Ы As port 28 but connected to the АСТА Transmit Clock. 
Port 30, . CTC Channel 2, read/write 


” As port 28 but connected to clock input of CTC channels 
@ and 1. 


Port 31, „ CTC Channel 3, read/write 

- As port 28 but not used. 
The clock input to CTC channel 2 is the system clock of 4MHz divided by 13 
giving a clock rate of 307692Hz. With the CTC divisor set to +1 and АСПА 


divisor set to +16 via the control register the ACIA output clock frequency 
is as follows:- 


стс р, 1 АСА 
Divisor Output 
64 300.48 Hz 
32 600.9 Hz 
16 1201.9 Hz 
8 2403.8 нг 
4 4807.7 Hz 


2 9615.4 Hz 
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А.? USER PORT INTERFACE 


The User ports provide a simple bi-directional parallel interface whereby a 
user device may be connected to a Newbrain processor. Either or both of the 
input and output parts may be used. The signals are:- 


Pin No. Function 
User Port In 1 og 
2 pi 
3 % 
4 эз 
5 м Data into Newbrain 
6 05 
7 06 
8 97 
9 USRST, User Status, into Newbrain 
10 USRINT, User Interrupt, into Newbrain 
п CLUSR, Clear User, from Newbrain 
12 GND, ground 
Pin No. Function 
User Port Out 1 W 
2 т 
3 2 
4 з 
5 М Data from Newbrain 
6 t5 
7 с6 
8 07 
9 USTRB, User Strobe, from Newbrain 
10 USRINT, User Interrupt, into Newbrain 
d n TLUSR, Clear User, from Newbrain 


2 GND, ground 
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The significant timing diagrams for the User Port interface are shown below. 


200ns 
— 
USTRE 
Data 
USRINT 
CLUSR 
- = 


200п5 тіп 


Data from the Newbrain becomes valid on the rising edge of USTRB. То allow for 
propagation delays the data lines should be read 1005 after USTRB becomes high. 
The CLUSR signal is a request by the Newbrain to reset USRINT. USRINT should go 
high while CLUSR is low. Other signals and protocols сап be defined by the user 
and their interpretation catered for within the user driver software. 
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APPENDIX B 
LIST OF ROUTINES 


ADHLA 
ADLIN 
лим 


BACAL 
BRKTST 


CALIN 
CALLNC 
CALLOS 
CALLRTN 
CASSERR 
CASSIN 
CASSOUT 
CLOSE(105) 
СОРІЅ 
COSNC 
СРОВ 
CURLT 
CURRT 


6.4.1 
6.4.4 
6.4.5 


6.4.2 
2.7.1 


6.4.3 
2.6 
2.6 
2.6 
2.5.1.2 
2.5.1.3 
2.5.1.5 
3.4 
2.5.1 
2.6 
6.4.9 
6.3.4.8 
6.3.4.2.6 


3.6 
3.8 
2.5.2 
37 


GETCUR 
GETCRO 
GETDE 

GETKEY 
GETREG 
GOTCHS 
GSPCBK 


HLTTCAPS 


ILIN 
IMMKEY 
INCOE 
INPUT( 10S) 
INTRPT 

loc 
IOPOFF 
10РОН 


JGIN 
JG0P. 
JGOUT 


N 
ө 
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KBCLS 7.5 TLOPIN 5.2 
кво 2.5.1.4 TOS = Top of Stack 
KBIINP 7.3 TPIOPI 44 
KBOPI 7.2 ТР20РІ 4.4 
KBOUT 7.4 TP10PO 4.2 
KBWINP 7.3 TP20PO 42 
KLOOK 7:7 TPCLS 4.6 
TPINP 4.5 
LIOPIN 5.2 TPOUT 4.3 
LPOPOU 8.2.1 TTCAPS 2.10.1 
LPOUT 8.2.2 TVCLS 5.5 
TVINP 5.4 
MKBUFF 3.9 TVOPIN 5.2 
MOVE (0S) 3.3 your 5.3 
тут 5.3.1 
OPEN( 10S) 3.2 
our 5.3.3 vpoc 8.2.3 
OUTPUT 3.3 
WLIN 6.4.10 
RDBLCK 4.8 
ROBYTE 2.10.4 WRBLCK 4.7 
RDIGIT 2.10.2 
RDINT 2.10.3 
ROKEY 7.6 
REGINT 2.5.11 
RESET 5.6 
SPACE 2.3 
STKTST 2.7.2 


Appendix C - Summary of Changes 


Except where otherwise stated all changes in function took place prior 
to the release of the NewBrain in May 1982 


Hardware 
References to other than Model A NewBrains in the body of this technica? 
manual should be ignored. Some of the hardware ports for the models M 


and V are implemented in the expansion interface module. Latest details of 
these are given in Appendix F. 


System parameters 
The following new system parameters һауе been added: 


Address Length Мапе Value 

6E 3 IOPON JP Entry to old IOPON routine 

n 3 IOPOFF ЈР Entry to old 10POFF routine 

74 ? DEFNF Default numeric format parameter for 
BASIC to supply to maths pack. 

75 1 STR11 current default graphics stream number 
for use by PLOT 

n 2 CHRROM | Memory address of start of 2k character 


pattern look up for text plotting in 
high resolution. 


05 


Оп power-up the check for а ROM at address АЙЙЙН will indicate а ROM is 
Present and the power-on routine continues in this ROM. A check is made 
to see if there is a ROM at address 8000Н (contained in an expansion module) 
and if so the power-on routine continues there (this facility is used to 
enter n paged memory operating system - POS - in the expansion interface 
module). 


In order for power-up to continue in the 8000Н address Ø of this ROM must have 
bit 7 set to zero, additionally ROM address 2 must not equal 8 (this curious 
restriction is necessary because in some NewBrains the АЙН ROM "wraps round" 
into the 8090H address space when no ROM is present in this space). 


The ROM at Ай) contains an intercept to provide new 2 - code routines. 
Details of these and the other 2 - code routines are given in Technical Note 10. 


This ROM also inserts а new ROM device table and sets its address in DEVTAB. 
The new device table substitutes new entry points for devices 9 and 4 (TVIO 
and TLIO) and a new device, device 11 (GRAPH). 


The ROM resets the BASIC restarts (RST 32 and RST 40) in order to intercept 
BASIC and allow for the PLOT command and graphics functions (ARC, MOVE etc). 


Power-on concludes by setting 57811 to zero (indicating no default graphics 
stream yet), DEVØ to 4 (TLIO), CHRROM to 08800Н (a 2K table is found at this 
location) and jumping to BASIC via UP. 
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IOPON and IOPOFF are now called directly at locations 006Е and 0071. These 
routines cater for power switching in battery powered New8rain models, and 
are therefore not really relevant to the A/AD models. The routine ACINIT 
has been removed - its functions are now catered for in the paged memory 
operating system. NEWIO has been replaced, but does not differ in functional 
specification or use of own memory. KLOOK has been rewritten to facilitate 
the production of foreign language keyboard versions. KBIIO and KBWIO use 
3 bytes of own memory in later releases of the software: location IX + 1 is 
not used but is reserved; location IX + 2 is used as an accent parameter. 
KLOOK will expect IX + 2 to be available for its own use, so 1X must be 
appropriately set up on entry to this routine (the amended versions of 1110, 
TVIO, TLIO, KBIIO and KBWIO al! do this automatically). Prior to first call 
the accent parameter must be set to Ø. Note that on exit from KLOOK with CY 
and 2 set HL >KBMODE. This latter fact is used by ROKEY! 


x19 


In the own memory vector locations IX + 2 and IX + 3, previously unused and 
used as follows: 


IX +2 Accent parameter (foreign keyboard versions only) 


IX + 3 — ORDEP - original depth = number of display lines held in buffer 
prior to opening of a graphics stream linked to this character 
stream. 


Х10 now takes account of the difference between ORDEP and DEP. 11015 no 
longer exits via IOPOFF. The video buffer start is now forced to an address 
of the form 128n * (LL/20) (to allow for certain behaviours іп the hardware). 


The routines REMCUR, WRNC, SHOCUR and WRC have been altered so that the criteria 
for the appearance or non-appearance of the cursor on the line display are 
identical to those previously applying to the screen display. 


XEDIT has been altered to support character sets 3 and 4 allowing 30 lines 
оп the screen. User contro! of TVMDI via the CONTROL W code is restricted by 
masking to bits 3, 1 and 0. 


TVCLS now prevents movement of video areas in memory except while the screen 
is blanked. 


BASIC 


PLOT routines are provided which automatically generate the appropriate character 
strings for the graphics device driver. 


DEFNF is set on entry for free format with 8 significant figures. BC is 


loaded from DEFNF prior to calling maths output when no user formatting 
(С) - notation) is used. 
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Rules for writing programs compatible with Expanded NewBrains 


Оп the face of it the only sort of program that can be written for an 
unexpanded New8rain is a BASIC program. However, such a program can 
RESERVE some memory, POKE machine code into it and CALL it. We restrict 
ourselves here to discussion of four sorts of program: BASIC programs, 
machine code subroutines to BASIC programs, Device Drivers and User 
programs. 


BASIC programs 


basic programs will run identically in expanded systems so long as no use 
is made of PEEK, POKE and CALL and identical device drivers are connected 


NOTE that the device number in an OPEN statement defaults to the “default 
back-up store device", which in the unexpanded NewBrain A/AD is device 1 
(TAPE 1). In disk systems it is the disk file system device 12. The 
device number shou!d therefore be specified if a particular device is re- 
quired. 


All communication with hardware must be via the input/output system e.g. 
PEEKing and POKEing the screen memory or the printer buffer is not com- 
patible with expanded systems. If input/output functions not implemented 
in the system are required then a standard format NewBrain Device Driver 
should be written to perform the functions (see below). 


Use of Graphics 


A maximum 220 screen lines of text graphics should be requested and the 
amount requested should be a multiple of 10 lines. It should be assumed 
that if 10n lines are requested then 24-n lines of characters are avail- 
able in the scrolling character area at the top of the screen (certain 
configurations provide 25-n lines, but only 24-n are guaranteed to be 
present). 


When opening the editor screen on which the high resolution graphics picture 
15 to be imposed, space for a minimum of 25+5.25 character lines should be 
requested. More than this will be required if the graphics FILL function 

is used and how much more can only be determined by experiment. If a program 
is to allow arbitrary shapes to be FILLed then an ON ERROR trap should be 
incorporated to intercept failures to fill complex shapes. 


No assumptions should be made as to whether or not a dot plotted on the 
boundary of the graphics area or up to one physical screen dot's distance 
from it will or will not actually appear on the screen. 


Do not assume PEN(x) is implemented for x7. 


No major assumptions should be made about the "smoothness" of diagonal lines 
or arcs. 


There are special rules for adapting a BASIC program for implementation in ROM. 
A software package for this purpose is to be released. Any BASIC program сап 
be adapted but if it is desired to implement part of the program in object code 
then that part should not contain any of the following commands, which cause 
Object code to be deleted: STOP, RUN, NEW, LOAD, MERGE, RESERVE, CLEAR, DELETE, 
and END; furthermore the program must never run out of memory. 
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Machine code subroutines 


An area of memory may be RESERVEd and a machine code subroutine POKEd 
into it and CALLed. Such a program may reference the BASIC interna 
dalastruclure, any data structures of its own in the RESERVE area and 
may interface with the operating system by Z-code calls only. This is 
explained under "CALL statement" and “05 routines" in the NewBrain Hand- 
book. 


А machine code subroutine must not reference OS datastructures, as these 
differ in expanded systems. 


No assumptions should be made about the internal format of floating 
point numbers - Maths Pack Z-code routines should be used to manipulate 
these. 


It is best to produce position-free or relocatable code for machine code 
routines, as the base of RESERVEd areas may vary 


For compatibility the following Z-code routines should not be used in 
programs intended to run on unexpanded NewBrains: FPHLF, FPIDZ, BICML, 
RDBYTE, RDINT, RONSP, BLKIN, BLKOUT and FSTRM (i.e. 2-codes 2 59). Calls 
to BLKIN and BLKOUT should in any case not be made with ВС» 256 or 

Чі 3 40960 or Н. < 8192. 


Device Drivers 


А device driver may be constructed, POKEd into RESERVEd memory and activated 
by adding it to the device table (see Technical Notes 7 and 9) 


For compatibility, such a driver should not request an own memory area 
greater than 8184 bytes. (In expanded systems, additional working space 
can be obtained from the memory management system; and in any case more of 
the RESERVEd area may be used if needs be). 


Since a device driver is likely to interface with the hardware no definite 
guarantee of compatibility сап be given - іп particular two different device 
drivers may act in contradiction in their demands on the hardware. However, 
817 hardware functions present in unexpanded NewBrains remain present in 
expanded ones, so modification, if necessary, is not likely to be difficult. 


Tne method of activating a device driver (given in Technical Note 9) does 
differ in expanded systems, though the necessary changes are not great. 
Device drivers will generally have to be relocated to run on expanded systems 


User programs 


User programs as defined in the body of this manual can be implemented in 
expanded systems. The entry parameters to the program itself and to the 
MKSPC and RETSPC routines are different but re-implementation is, as with 
the device drivers, not difficult. 


Short-cut 


A utility is provided for expanded systems which cause them to reconfigure 
themselves as Unexpanded. If this utility is run then any program written 
for an unexpanded system can be run completely unmodified. It cannot, however, 
take advantage of the expansions. Such a program must not make any assum- 
ptions sbout the memory space SU gH-9FFFH. 
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Appendix 6 - Technical Notes 


Technical Notes may contain information that has been duplicated 
elsewhere in the manua! but is repeated here for your convenience 
Further Technical Notes will be issued from time to time and should 
be inserted at the back of this manual. 


Technical Notes 


1 VF display character set 
Y NewBrain keyboard codings 
3 NewBrain keyboard codings (France) 
4  NewBrain printer interface 
5 Memory Allocation 
6 NewBrain BASIC - General Description 

7 105 

8 Use of own memory by standard device drivers 
9 Patching a device driver 

10 Operating system routines 

11 Access to screen display characters 

12  New8rain BASIC reserved words 

13 Keyboard sequences 

14  NewBrain BASIC - Technical Specification 

15 Тһе NewBrain Graphics Package 

16 Screen Editor - Technical Specification 
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Technical Note 1 Issue 1 (NewBrain AD) 


VF display character set 

There are 128 characters, pictured below. 

О! these only 65 can be displayed using NewBrain device drivers 3(VF display editor) and 4(combined 
screen and VF displey editor) These 65 are VF display characters 32-94 (the ASCII characters 32-94), 
VF display character 95 (the © sign. screen character 228) and VF display character 104 (this is used for 
characters "unrecognisable" to the VF display). Drivers 3 and 4 recode the character sel so code 168 is 
displayed as “©”, codes 97-122 (ASCII lower case letters) are displayed as VF characters 65-90 (their 
Upper case equivalents) and codes 0-31, 95, 96, 121-167 and 169-254 are displayed as 
"unrecognisabie" 

Ай the characters can, however, be displayed if devices 3 and 4 are not in use, by poking them into the 
appropriate area of memory. 280 address 62 corresponds to the right-most position in the VF display, 63 to 
the next left Irom it and so on. 

VF display position 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 


11200000000 Ш: 


Memory address 77 76 75 74 73 72 71 70 69 68 67 66 65 64 63 62 
When the memory has been set up the display must be activated by the command 
POKE 59, 160 
This command must be repeated whenever the display contents are changed. 
Example: 
To display the message "NEWBRAIN BASIC " 
10 A$-"NEWBRAIN BASIC 
- 20 FOR != 1 to 16: POKE 78-1, ASCIMIDSIAS, I): NEXT I 
30 РОКЕ 59, 160 
40 END 
M the top bit (bit 7) of the code is sel then the character will flash. 
Example: 
To fill the VF display with flashing N 
FOR |= 62 to 77: POKE I, 128--А5ССХ?): NEXT I 
POKE 59, 160 


LIN N- , х ум NE 
ANAY ANNE 
0 1 2 3 4 5 9 
МЕЕ NC T ut к. 
Vla Saha £X 
"ОН иу Y 
di 7 

A 

г 

ә 

i 

* 

73 

L 

a 


— 1 

LLIN VN A Их и 
105 106 107 108 109 1 
A TAT _ КЕШЕ 
М АМ 7\ UIN ANE 7 LI 
121 122 123 124 125 126 12 
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Technical Note 2 Issue 1 (NewBrain A/AD UK) 


NewBrain keyboard codings 
The keyboard can be accessed by the user via devices 5 and 6 or by a screen or line editor device (0,3 or 4). 
The values returned by the keys are shown in the diagram. The values returned may be modified by 
“keyboard attributes" (shitt-lock, graphics-shift, secondary-graphics and tertiary-graphics) in force at the 
time of access. Which attributes are in force is determined by the "keyboard mode", a single value in the 
range 0-9. A separate keyboard mode is maintained by each device 5 ог 6, bul a single mode value is 
maintained by the keyboard software itself for all accesses of the keyboard by editor devices. The mode 
value lor editor devices is set by the user entering control 0- control Э or control * (these sel the mode to 
the same number, contro! * to value д). The mode is set for keyboard devices by PUTIing to the device, 
according to the table: 
PUT value for Control key for 

де devices 5 and 6 editor devices 

Oor8 0 075 

109 


“ 


5 


S 
(a! 080v 
o 


Modes 8 ала 9 are not available to devices 5 and 6. 

Тһе modes set the attributes as follows. 

Mode Keyboard attributes in force 
^ 0 
shilt-lock 
graphics-shitt 
Shift-lock, graphics-shitt 
secondary-graphics 
Shift-lock, secondary-graphics 
graphics-shitt, secondary-graphics 
shift-lock, graphics-shift, secondary-graphics 
graphics-shitt, tertiary-graphics. 
shift-lock, graphics-shift, tertiary-graphics 


The keyboard attributes modify returned values only as detailed below. 


O 


shift-lock: The unshited keys A-Z return the capitals A-Z (le. keys normally 
retuming codes 97-122 return 65-90) 

graphics-shitt The shifted keys =, A-Z. (-) and + (which normally produce codes 
64-94 respectively) produce graphics codes 224-254. 

secondary-graphics: The keys =, A-Z, . j and + when used with graphics (which normally 
produce codes 128-158, respectively) produce graphics codes 
160-190, 

terliary-graphics The keys =, A-Z, (-) and + when used with graphics produce 


graphics codes 192-222. 


value of key value of shifted key 
— 


Control and graphics of 0-9 and * return value ꝙ io keyboard devices 5 
value of key with contro! value of key with graphics and б, and do по! return values to editor devices. 


50 34 35 s2 36] [эз 37] [54 зв 
2 3 4 5 в 


57 es] [ns эз] [оо вв 43 94 
омо А 5 о + 
1129 9 


sa} [2r 15 
3 ESCAPE 
wa] [гв 156 9 16 


NEWLINE 
4132 30 158 3 16 


5 
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Technical Note З Issue 1 (NewBrain A/AD FRANCE) 


NewBrain keyboard codings 

The keyboard can be accessed by the user via devices 5 and 6 or by a screen orline editor device (0,3 or 4) 
The values returned by the keys are shown in the diagram. The values returned may be modified, in Ihe case 
о! certain keys, by first typing an accent, circumflex ^ or tréma `. The values returned may also be modilied 
by"keyboard attributes” (shíft-lock, graphies-shitt, secondary-graphics and tertiary-graphics) in force at he 
time o! access. Which attributes are in force is determined by the "keyboard mode a single value in the 
range 0-9. A separate keyboard mode is maintained by each device 5 or 6, but a single mode value is 
maintained by the keyboard software itselt for all accesses of the keyboard by editor devices. The mode 
value for editor devices is set by the user entering control 2 to contro! 9 or contro! * (these set the mode to 
the same number, control * to value 0) The mode is set for keyboard devices by PUTting to the device, 
according to the table: 


PUT value tor Control key for 
Mode devices 5 and 6 editor devices. 
0 Ооё 00” 
1 109 1 
2 2 2 
3 3 3 
4 4 4 
5 5 5 
6 6 6 
7 7 7 
в - 8 
3 = 9 
Modes 8 and 9 аге not available 10 devices 5 алд 


The modes set the attributes as follows 
Mode Keyboard altributes in force 


shil-lock 
graphics-shitt 

shift-lock, graphics-shitt 

secondary-graphics 

shift lock, secondary-graphics 

graphics-shilt, secondary-graphics 

Shitt-lock, graphics-shift, secondary-graphics 

graphics-shilt, tertiary-graphics 

Shittlock, graphics-stuft, tertiary-graphics 

When а circumflex accent or tréma is typed. the value zero is returned for keyboard devices 5 and 6, and 
no value is returned to editor devices. A coded value is set for the device driver to indicate that the accent has 
been typed, and if the next key typed is one of those in the tables given below, a modified valve is returned, 


S 


Alter circumtlex: А 2. code 205 
E ё. code 210 
l 1. code 213 
о ©. code 217 
9 0. code222 
space ^. code 251 
After tréma: 1 code 214 
u 0. собе 223 
The keyboard attributes modily returned values only as detailed below: 
shitt-lock The unshifted keys A-Z return the capitals A-Z (е. keys normally 


returning codes 97-122 return 65-90), and the numeric keys 0-9 
(which normally produce coces 204, 38, 208, 34, 39, 40, 248, 209, 33, 
and 225) return the numbers 0-9 (ie. codes 48-57). 

graphics-shitt The shifted keys, A-Z and - which normally produce codes 65-90, 
95 respectively) produce graphics codes 225-250, 255. 

secondary-graphics The keys. A-Z and ~. when used with graphics (which normally 
produce codes 129-154, 159, respectively) produce graphics codes 
161-186, 191 

tertiary-graphics: The keys, A-Z and —, when used with graphics produce graphics 
codes 193-218, 223. 
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Technical Note 4 Issue 1 


NewBrain printer interface 
The NewBrain serial printer interface is a simple RS232C/V24 interface running on 3 wires- DATA, 
READY and GROUND. Data is transmitted as 8 dala bits with 2 stop bits and no parity. The communications 
protocol is a "ready/busy handshake” in which the printer indicates thet it is ready to receive data by an 
ОМ condition (also known as a SPACE, "0", binary 0, positive or high voltage condition) of the READY lin 
and indicates that il is not ready to receive data (i.e. busy) by an OFF condition (also known as a MARK, "T 
binary 1, negative or low voltage conditioni 
Connecting up a printer 
Ап RS232/V24 serial interface printer is usually connected via a 25-way D-type connector. The actual 
wiring varies from printer to printer and general instructions are given here. The printer manual should be 
consulted to determine what the correct connections are. Note that a fully specified V24 interface (such as 
that on the NewBrain) cannot be damaged by a mis-wiring of the connector, but that Grundy Business 
Systems Ltd cannot be held liable tor any damage which might occur to a prinier or a NewBrain if they are 
mis-wired, or for any consequences ol it, and therefore a check should be made with the printer supplier if 
there is any doubt about the interconnection. 
The printer may be configured as a “Data Communication Equipment" (ОСЕ - usually the printer is fitted 
with a male D-type socket and temale D-type plug is required) or, as is usual, "Data Terminal Equipment” 
(DTE - usually the printer is fitted with a temale D-type socket and a male D-type plug is required) 
(a) Connecting to a printer configured as DTE 
The green wire (DATA) is connected to pin 3 of the D-type ("Received Data”, АХО). The screen (GROUND) 
is connected to pin 7 ("signal ground", SG). The blue wire (READY) is variously connected to pin 11 
(Secondary", “supervisory” or "backward channel") or ріп 20 (“Data Terminal Ready", DTR). It may be 
necessary to make certain other connections within the D-type connector lo ensure the printer responds 
to data — in particular pin 4 ("Request to send", RTS) to pin 5 ("Clear to send”, CTS) and pin 20 (DTR) to pins 
6 (“Data Set Ready”, 058) and pin 8 ("Data carrier detect", DCD). The red and yellow wires are not used. 
(b) Connecting to a printer configured as DCE 
The green wire is connected to pin 2 of the D-type ("Transmitted Data", TXD), the screen (GROUND) is 
connected to pin 7 ("signal ground. SG) and the blue wire (READY) is connected either to pin 5 ("Clear to 
send", CTS) or to pin 6 ("data ͤ in the case оға printer configured as ОТЕ surplus signals 
may have to be mopped up by connecting, for example, RTS to CTS and/or OTR to DSR. The red and yellow 
wires are not used. 


Using the printer 


Enter 
OPEN # 8, 8, 2400 
to op a 2400 baud printer. И possible the printer should be set to 9600 baud as this is the default value 
зо one need enter only 


OPEN # 8,8 
and in any case it is best to run the interface as fast as possibie. 
Now switch the printer on. 
To list programs to the printer then enter 
LST*8 
or LIST # 8, 100-300 
to list lines 100 to 300. 


To print data enter 

PRINT # 8, "helio printer” 

PRINT# 8, 2+3; a$(14), х1 
The syntax is the same as PRINT to the screen, but the TAB function is equivalent to a comma ij separator 
regardless of the TAB value. The zone width г. is 8 columns. 
The printer driver will automatically issue tine feed (character 10) after newline (character 13). An automatic 
newline, line feed, is issued after 80 characters have been printed if a newline is nol entered anyway. 
If the user wishes to avoid the auto line feed and print zoning then device 9 should be used instead of 
device 8 and the printer lead should be piugged into the COMMS socket on the back of the NewBrain 
instead of the PRINTER socket TAB and comma () will resultin the issue of TAB control codes (character 9). 
For both device 8 and device 9 controi codes сап be sent to the printer using PUT statements. 

eg. PUT#8,12 0“ form leed 

PUT # 8, 27,30 -an escape sequence 
Details of the Communications protocol 
On power-up the DATA line is іп the binary 0 condition. It remains in this condition until a printer device 


(device 8) has been OPENed. Thereafter il remains in the binary 1 condition between data bytes, even if all 
printer devices are CLOSED. 

Data is transmitted on the DATA line. Data transmission will not start unless the READY line is in the ON 
condition. The READY line is sampled before any and every data byte is sent. If no connection is made to 
the READY line an ON condition is assumed. A transition of the READY tine from ON to OFF during 
transmission of a byte will not inhibit completion of transmission of the byte nor cause an error condition in 
the NewBrain nor cause retransmission of the byte. The DATA byte is sent as a "start bit" (binary 0), 8 data 
bits (least significant bit sent first, a binary 0 represents a zero in the corresponding bit of the byte, a binary 
1 a one) and two “stop bits” (binary 1). Between bytes the DATA line remains at the stop bit level (binary 1). 
Typical voltage levels 

A DATA binary 1 is set by the NewBrain at -9 volts. A DATA binary 0 із set at +9 volts. 

A transition of the READY line in an ON state to a voltage < —3 volts is interpreted as a transition to an OFF 


state. A transition of the READY in an OFF state to a voltage > 3 volts is interpreted as a transition to ал ON 
state. 


A Typical Printer Lead Wiring 


green RXD 
RTS 
ст 


DSR 


SCREEN 
GROUND 


80 
DTR 
DCD 


BCRTS 


AAA 
AA ready 
N NN 3-polansing insert 

VN Neda 25 way 

N 5 S-type 
е male, wiring side 


Technical Note 5 Issue 1 (NewBrain A/AD unexpanded) 


Memory Allocation 

The sollware modules which make use о! memory are 
The operating system (05) 

The Maths Pack (MAT3) 

The Hardware STACK 

The Input/Output System (05) 


The BASIC 
OS, Mala and the STACK are allocated fixed amounts of memory. Memory allocation lo 105 and BASIC 
is dynamic. 
0000 
OS area 
256 bytes | 
0100 
МАТЗ area 
160 bytes 
01A0 
STACK area 
200 bytes. 
OR 0268 
105 
area 
STRTOP/BSPRM—> [177 variable 
BASIC 
area 
B4 ТЕҒЕ 
8000 
Pointers to memory bounds are kept at fixed locations in the OS area 
0062 1058АМ The base of the 105 area. 
0064 STRTOP The top of the !OS area. 
0004 ВЗРАМ The base о! the BASIC area. 
0006 B4 The top of the BASIC area. 
Painters to the base of an area point into the area and pointers tothe top of an area point to the first address 
по! used. 


B3PRM and B4 are entry parameters to the BASIC Atter entry they are not again referenced by the BASIC. 
!OSRAM and STRTOP are constantly relerenced оу IOS. 

The current software keeps (IOSRAM) static at the top o! the STACK area, keeps (STRTOP) equal to 
(B3PRM) at the dynamic bound between the IOS area and the BASIC area, and keeps (B4) static at wo 
bytes short of the true юр of RAM. 

Use of memory areas 

1 Обаға 

This is used exclusively for static parameters concerned with OS tasks (ie. interrupt handling, memory 
management and communication between modules), The locations relevant to this discussion are di 
above 


2 Marg area 

The first six bytes of this area is the floating point accumulator FACC: it is used to pass arguments to and 
from the maths pack. Four bytes of the area. RANDNO, are used internally as а permanently maintained 
seed for the random number generator. A pointer to an ASCI! string in the maths pack area is returned by the 
maths routine OUT which converts floating point to text Otherwise the area is used only internally by the 
maths pack as а scratch pad 


ҒАСС 0100 


RANDNO 0137 
01A0 
3 STACK area 
0150 
SP+] 
IOSRAM> 0268 


This is used by the Z80 hardware stack pointer in the usual way. The stack grows downwards in memory, 

so the active end of the stack {often called the “top of the stack") is below the stack memory area top. In the 

unexpanded NewBrain the user may move the stack pointer elsewnere but must allow 64 bytes free below it 

for interrupt handling. Initially the stack pointer is set to the top of the area, іе. at (OSRAM). 

4 105 area 1 
105 maintains a stream table, which is a list of active streams, and for each active stream an “own memory 

area". Initially there are no streams open and so IOS requires no memory, (О5ВАМ) = (B3PRM). 


IOSRAM 0268 


STRTAB | 
stream 
table 


ЅТЯТОР-» 


When steams are opened new stream table entries are made at STRTOP and new own memory areas at 
STRTAB, another OS fixed location parameter. Memory space is taken from BASIC via OS. 

0056 STRTAB pointer to base of stream lable 

When streams are opened new stream table entries are made at STRTOP and new own memory areas at 
data structures moved down to close up the area. Memory space is returned to BASIC via OS. 


The stream table consists of six byte entries containing pointers to the bases о! the corresponding own 
memory areas: 


steam number 


device number 


reserved 


5 BASIC area 


BASIC uses IY to index the base о! its area and the first 61 locations contain general parameters and 
pointers. The remainder of the area is used to hold the уапоцв BASIC data structures 


ү-----> 


(B3PRM) on entry 


1Үтбі 
stop 
ОТОР 
USRSTP 
User Stack 
FORPTR 
FOR Block Area 
GSSPTR 
GOSUB Stack 
STBAS 
ARBAS 
5ВА5 
LBAS 
Line Number 
Tabie 
TOP 
RESERVED 
Area 


(84) on entry 


‘The various pointers which delineate the areas within the BASIC area are heid in me first 61 bytes at offsets 
from IY: 


+0Е STOP top of source code area 
+10 ОТОР top of object code area 
+12 USRSTP user stack pointer 

+14 FORPTR FOR block stack pointer 
+16 GSSPTR GOSUB stack pointer 
+18 STBAS string area base 

ЖЗА АНВА5 алау area base 

119 SBAS symbol table base 

+1Е LBAS line number table base 
*20 TOP top of line number table 


Initially no memory is used by the datastructures so ОТОР- STOP = IY--61, 
ЏЅАЅТР = FORPTR = GSSPTR= STBAS = ARBAS = SBAS = LBAS = TOP. 


Ав memory is allocated and deallocated all areas are kept permanently closed up. 


When memory is requested by the operating system the lower data structures are moved up into the free 
area. When it is returned they are moved back down. 


When memory is obtained with the RESERVE statement the upper data structures are moved down into the 
ree area. 


Aub L 
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NEWBRAIN BASIC- GENERAL DESCRIPTION 

NewBrain Basic is an interactive compiler. Each iine is compiled separately, and only when execution о! 
a line is required when it has not been previously compiled. This means that in normal circumstances lines 
are only compiled once, and execution is thus very efficient. 

Occasionally. for example when RAM runs out, or when instructions of an exotic nature are used, the object 
Code is deleted. No significant overhead is caused by this, unless there is very little spare RAM or the exotic 
instructions are used repeatedly. 

Since the object code consists of pointers into both symbol table and line-number table, these are fixed 
during execution, and the instructions that alter them (e.g. DELETE, RESERVE. CLEAR, MERGE) cause 
the object code to be deleted. 

The source lines are compressed by exchanging reserved words for 1-byte tokens. The SAVE command 
outputs this compressed version, reducing time spent saving and re-loading programs. Multi-statement 
lines are split up in their internal format 

The RAM used by the BASIC has a dynamic lower bound, which the operating system can move by means of 
the MKSPC and RETSPC routines. The upper bound is also dynamic, but can only be moved by the 
RESERVE command. Space reserved cannot be given back in а simple manner. 

The object code consists of 1-byte operators (Y-codes) which may or may not have arguments, which index 
а table of run-time routines (X-routines}, which perlorm the run-time operations. Within the BASIC, 

‘compilation and execution routines are entirely separate (with the exception of the OPTION and CLEAR 
statements), except that they can use the upper store management routines, and some basic 1/0 utilities. 


RAM Organisation 


Low address * | 
IY6t Fixed locations. 
Source code area 
STOP 
Object code area 
ОТОР 
Free memory 
USRPTA 
User-stack 
FORPTR 
For-blocks area 
GssPTa 
Gosub-stack 
STBAS 
String area 
ARBAS 
Array area 
seas 
Symbol table 
LBAS 
High address ынйы 


Fixed Locations 


Displacement 
from IY 


Displacement 
from IY 
6 


35 
37 
39 
42 


43 
44 


46 


47 
49 
51 
53 
55 
57 
59 


Size 


enn 


е 


OUTCON 
INCON 
ERRNO 
INPTR 
SVINPT 
STOP 
OTOP 
USRSTP 
FORPTR 
GSSPTR 
5ТВА5 
ARBAS 
SBAS 
LBAS 
TOP 


FLAGS 


NCONNO 
SCONNO 
CLINNO 
BASFLG 


@TYPE 
OMOVE 


PPFLGS 


DTINeT 
DTLN 
FORVAR 
APAR 
FPAR 
ERRLIN 


BRKLIN 


Descriptions 


Descriptions 

The stream to which output is currently being made. 

The stream from which input is currently being taken. 

The number of the last error or interrupt that occured in program 
execution. 

Тһе position trom which ROCH etc. are taking their input. 

Spare. 

Atemporary memory for input positions, used by SVINST and RSINST. 
Points to Top of Source code. 

Points to Top of Odject code. 

The base of the User-stack. 

The base of the For-biocks area. 

The base of the Gosub-stack. 

The base of the String area. 

The base о! the Array area. 

The base of the Symbol table. 

The base of the Line-number table. 

The top of the Basic RAM area, which can be moved down with the 
RESERVE command. 

Bit 0 is set during running - used by INITOB. 

Bit 1 is set if interrupts are 10 be ignored. 

вази Set if tokens are not to be expanded during listing (i.e. during 
Bit 3 s set during compilation used by INITOB. 

Bit 4 is set whilst Compiling a DEF so that VARIAB can watch for formal 
parameter occurrences. 

Bit 5 is set if compilation is not to produce code. 

Bit 6 is set i! INPTR is relative Io USRSTP currently. 

Count of number of numeric constants encountered, to give each onea 
Unique n/t. Not currently implemented. 

Count of number of string constants encountered, but 14 is always set. 
Not currently implemented. 

Holds the line-number and displacement where last break of execution 
in the program occurred. 

Bit 0 = base ді arrays (either 0 or 1). 

Bit 7 = lower base is now fixed il set 

Temporary variable for EXPN. 

The amount by which the object code has moved during execution 
ot a line. 

Bit 0 set if in a quoted string. 

Bit 1 set if after REM or DATA. 

Bit 2 set during SAVE. 

ВИЗ set it ali KWDS should be tested for, clear if only initial ones should 
бе, or on output whether а token is trom KWDS (clear) or OKWDS (set). 
‘The displacement of the ‘DATA pointer in the source DTLN. Only 1-byte 
is used, but Ihe other cannot be used for anything else. 

The current line number for the ‘DATA pointer’. Changes to the LNT 
entry while executing READ. 

Temporary variable in CFOR, holds the name type o! the FOR statement. 
variable whilst searching for the NEXT. 

Holds the absolute address of the actual parameter (on the user-stack) 
during execution of DEF statements, accessed by XAATOF. 

Holds the name type ol formal parameter during compilation of DEF 
statements, with which VARIAS compares variables il finds. 

Where control is passed to, on program error. (f this is zero then no 
trap exists) 

Where contro! is passed to il a break-in occurs. (If this is zero then no 
trap exists) 


Source Code Area 

The source lines of the program and ine command line are held here When old ones are deleted, the others 
are moved down. New ones are added а! ТОР Lines are held in a tokened form. each token relerring to а 
KWD. the syntactic position giving whether it is trom KWDS оғ OKWDS. “Invisible THENS" are used to 
facilitate this, The ordering of the source lines is not significant. Each one ends in a carriage return, which 
replaced the ":” in mullistatement lines. which are spilt n the source area. The source code pointers іп ine 
line number table point to the first character of the line. Line numbers are nol held in the source area but 
leading and trailing spaces are 

Object Code Area 

An object code line is preceded by a2-byte count giving the length inclusive) of Ine object code for that line. 
There is no significance in the ordering of the lines. New ones are added at OTOP. The object code pointers 
inthe LNT point to the first object code byte (not the count). As the object code has many pointers tothe LNT 
and symbol table, any alterations to these, other than adding symbols at SBAS, require deletion of the 
object code 

User-stack 


The user-stack provides the stack that the object code interpreter uses when а Y-code demands a pushing 
ога popping. О! note is that for-blocks grow initially in the user-stack and get taken over by FORPTR, and 
also the following special constructions that may exist on the user-stack on execution o! a user-defined 
function. 


(a) No parameter 


Low address. Area where evaluation of function takes place and answer ends up. 


LNT pointer of DEF statement (2 bytes) 


High address Previous contents on stack. 


(b) Numeric parameter 


Low address 
APAR 


parameter 

АРАЯ+6 

LNT pointer of DEF statement 
APAR+8 


High address 
(c) String parameter 


Low address 
— APAR 
— 


APAR+4—ARBAS 
length of string 


APAR+2 
APAR+4 


string parameter 


APAR+4+(APAR+2) 


LNT entry of DEF 
APAR+6+(APAR+2) 


High address 


In both (b) and (cj the areas above the top line and beneath the bottom line are the same as in (a). In (c) what 
is found at АРАН must be made to оок like а S.T. entry for a string. In all cases Ihe material between the 
top and bottom lines is removed after evaluation of the user-defined function, so that the answer sits nicely 
where it should do on the user-stack afterwards. 


During Y-code execution strings on the user-stack are represented by a 2-byte count followed by the actual 
string, the count being the non-inclusive length of Ihe string. Numbers are just represented by their 6-byle 
floating-point representation. 

The user-stack is also used as an input butter for input from the operating system. Input is collected 
character by character on the slack until a line has been collected. and then the string of characters 
including the carriage return. is inverted and referenced by INPTR. This operation is performed by RDLINE. 


For-Block Area 
A block looks like this 


Low address %0 
LNT pointer for NEXT line 
+3 
LNT pointer for FOR line. 
+6 
Step Number 
E 
Limit Number 
+18 
2o ЗТ. pointer for FOR variable 
High address 


The for-blocks grow out of the user-stack. There are 2-bytes reserved for the LNT entries because under 
certain circumstances they are converted to line-numbers and displacements. At this time the symbol is 
converted to a name/type. 

GOSUB-Stack 

This consists of 3-byte entries, containing the LNT's of the GOSUB statements that have yet to be RETurned 
from, the most recent having the lower addresses. 3-bytes are used because at suitable times they are 
converted to line-numbers and displacements. 

String-Area 

The string-area contains only the actua! strings, which are in no particular order. Pointers into the string-area. 
are relative to ARBAS, as new arrays and symbols can appear at any time. When one is deleted, pointers 
into the string-area һауе to be updated (routine MKNULL). 

Array Area 

The array area contains only the elements of the arrays, each of which is 6 bytes. In the case о! a numeric 
array, the 6-byles are the floating point numbers; in the case of a string array, the elements аге: 


Low address 10 pointer into string area (relative to ARBAS) 
+4 length of string 
High address +6 spare 


The low numbered elements lie at low order addresses, and in the case of а 2-dimensional array, the 
elements are ordered (0,0), (0,1)....(1.0}, (1.11.2)... so the position of an element is 

BASE- (1s! 55) * (2nd DIM)" (2nd SS). 

Since new symbols can be made а! any time, the pointers into the array area are relative lo SBAS. When 
arrays are deleted, the pointers have to be updated (routine ARNULL). 

Symbol Table (57) 

All symbols are g. bytes in size The first two contain the name-type. The low order 10 bits of the name-type. 
“nA of a constant are zero. For a variable, the low order 10 bits are a coding of the variabie (made by routine 
GETVNM), which is: 

37 * (first letter from 0-25) + (if nothing eise then 36, else if it is a digit then 26 + the digit else the second letter 
from 0-25) The other bits are used as follows 

Bi10 Spare 

ви 11 = 1 if a user-defined function, otherwise 0. 

Bit 12 = 1 for a 1-dimensional array, or if a user-defined function, then it has a numeric parameter. 


Bit!3 =1 fora 2-dimensional array. or il a user-defined function, then it has a string parameter. 


Bit14 = 1 ifasstring constant, string array, siring variable, ot a user-defined function with a string result, 
otherwise. 
suis =0 if a constant, 1 otherwise. 


For an array, if both bits 12 and 13 are set, this means that it is not certain yet wnat number of dimensions 
the array has. For a user-defined function, it both bits are clear, the function has no parameters. 
The other 6 bytes are used as follows: 
(1) Numeric variable or constant 
The F.P. representation о! the constant or the current value of the variable is stored. 
(2) String variabie or constant 
+? 


position in string area relative to ARBAS 
+4 


+6 length of string 
+в Spare 
(3) Arrays 


position in array area relative to SBAS 
151 dimension 
2nd dimension, or 0 И 1 dimensional атау 


(4) User-delined function 
The other 6 bytes are unused 
New symbols are added al the base o! he symbol table (SBAS) which reserves the validity of the absolute 


pointers in the object code. Deletion of symbols (by CLEAR command) does not, so the object code has 
io be deleted. t 


Line-Number Table (LNT) 
The format of a line-number entry із: 
+0 
The line number 
+2 
The pointer to the source code 
+4 
Pointer to object code (0 if not currently compiled) 
+6 
The entries are always held in order by line-number, low numbered lines having low addresses. Multi- 


statement lines have a separate entry lor each statement, each having the same line-number, and are held in 
the correct textual order. If the line number is 0, the line is, or is part of, the command line. 


BGSA 209.1982 


беда” 
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105 

The NewBrain hardware and software architecture provides no barrier to 1/0 bus and memory bus access 
by a user machine code program. 

It is thus possible for the user program to communicate directly with any input/output device. However, this 
approach is nol recommended as NewBrain architecture is complex and protocols for the different devices 
are various. In any case direct access to a device in a user program is bad software practice- it makes it 
difficult to transfer the program to different devices and tempts the programmer to take advantage of specific 
features which may be absent in another environment, even when Ihe same functional device is present. 
All NewBrain devices are provided with device driver programs which make device interfaces appear 
identical. More precisely all devices appear to be single byte serial. This interface was adopted because it is 
very simple and straightlorward - any physical device can be made lo appear as byte serial, while more 
Complex interface protocols, such as block transfer or random access, can still be implemented in the 
device driver or the user program. 

Users are advised when implementing physical devices to write device drivers for them which are in accord 
with the standard NewBrain interface, or to use one of the standard NewBrain device drivers already 
implementec. 

To turther simplify the I/O interface a common set of calling routines, IOS, is provided to enter device drivers. 
Using these routines all communication with device drivers is via di streams (sometimes known as 
channels, logical devices or logica! units). Routines are provided to initialise a device driver, assign it a data 
Stream, allocate own memory to it, communicate with it and close it down. 

IL is recommended that all communication with devices is via these routines - since firstly this avoids the 
user having to дегі with the NewBrain memory management system directly, secondly all communication 
being via data streams the dependence of a user program on its environment is decreased, 

Device Drivers 

The existence of a device driver is made known to IOS by the presence of its entry address in the device table. 
The device table is pointed to by the contents of O/S fixed location DEVTAB. 

0058 DEVTAB Address ol device table 


Fig. 1: Device table 


DEVTAB 
Number of entries = n 


Driver address for driver 0 


<=} Driver adores for driver 1 


Driver address for driver п-1 


The first byte of the device tabie gives the number of entries (this may be zero - so at most 255 device drivers 
сап be known to IOS at one time). The subsequent bytes are the entries, each entry being а 2 byte device 
driver address in standard 280 iow-high format. 

In calls to IOS, a device driver is referenced by its “driver number", the number being its entry number in 
the device tabie. The standard NewBrain operating system contains a device table іп ROM with entries for 
the NewBrain supplied device drivers. When a user-implemented device driver is required the device table 
may be kept in RAM. 


Fig. 2: NewBrain ROM standard device table 


DEFB 12 ; Number of entries 
DEFW TV10 Screen editor 
DEFW ТРИО ; Tape 1 

DEFW TP2IO Таре 2 


DEFW ШО 1 VF display editor 


DEFW TLIO : Screen editor with VF display 


DEFW KBWIO 1 Keyboard 

DEFW KBIIO Keyboard with immediate return 
DEFW UPIO ; User port 

DEFW LPIO 1 Software seria! printer. 

DEFW JGIO 1 Software V24 

DEFW DUMMY 1 Null device 

DEFW GRAPH 2 High resolution graphics 


Each device driver consists of five or more routines; the first five are OPENIN, OPNOUT, INPUT, OUTPUT 
and CLOSE. The interfaces to OPENIN and OPNOUT are identical - a physical port number and logical 
parameter string are passed to the routine, which is expected to initialise tne device. 

When called via IOS the open routine may call MKBUFF in order to create own memory space. Open 
routines are expected to return to parameter string. The interface to INPUT, OUTPUT and CLOSE is simpler- 
‘one byle and a parameter, the port number, are passed lo the rouline and one byte is returned. 

105 Calling Routines 

A set of routines is provided 10 handle ай communication between the user program (e.g. BASIC) and 
NewBrain devices. These routines (OPENIN, OPNOUT, INPUT, OUTPUT, CLOSE etc) first identity the 
device driver to be used and then cali the corresponding routine trom the device driver. OPENIN and 
OPNOUT allocate a stream to the device, subsequent calls to INPUT, OUTPUT and CLOSE then reference 
the stream rather than the driver number and port number. As mentioned above device driver open routines 
may са! MKBUFF lo allocate own memory to a device, the address ol this memory is passed lo the device 
driver on calls to INPUT, OUTPUT and CLOSE. On return from a device driver CLOSE routine the stream and 
the own memory are deallocaled by 105. A restriction is made on own memory that it should not be 
absolutely relerenced. This is because CLOSEing one device may cause the own memory lor another 
device to be moved. This restriction can be got round in specific cases, but to ensure generality of use 
programmers are advised to adhere to it. Typically it is assumed own memory is used for parameters, counts, 
butters and relative pointers into buffers. 

105 Data Structure 

This consists of a sel of eight 2 byte pointers at fixed absolute addresses and a memory area which is 
maintained dynamically. The dynamically maintained area consists o! the stream table (al the top of the area) 
and a general purpose area, the primary use of whichis to hold the own memory areas lor the device drivers 
corresponding to open streams. Pointer OSRAM points to the base ol the dynamic area, STRTAB points to 
the base of the stream table and STRTOP points to the top of the stream table which is the top of the dynamic 
area. DEVTAB is one of Ihe pointers and the remaining four for extension or use by device drivers. 


0056 STRTAB Address of start of stream table 
0058 DEVTAB Address of device table 

005A TVCUR Used for XIO device driver 
005С ТУНАМ Used for XIO device driver 
005Е ОТНЕВ! Reserved for extensions 

0060 OTHER2 Reserved for extensions 

0062 IOSRAM Base о! IOS data structure 


0064 STRTOP Too о! stream table 


Fig. 3: IOS Datastructure 


STRTAB 


DEVTAB 


pointers 
used by 
device 
drivers. 

or for 
expansion 


IOSRAM 


STRTOP 


The stream table consists of six byte entries; the entries contain (from the low address end) the one byte 
stream number, the one byle driver number, the one byte port number, one byte reserved for expansion and 
the two byte pointer to the associated own memory area 


Fig. 4: Stream table entry 
stream 


driver 
port 
reserved for expansion 


‘own memory address 


When а stream is allocated by IOS open the stream table entry is added al (STRTOP). When own memory is 
allocated by MKBUFF it is added al (STRTAB) and the stream tabie is shifted up. The own memory entry in a 
stream table entry is set to zero initially and if a driver requires no own memory it should be left at zero. The 
‘own memory address may be set by the device driver to point outside the IOS data structure - ifthis is done it 
is the user's responsibility, though generally ^as no ill consequences for IOS. When streams and own 
memory are removed by CLOSE the IOS data structure is closed up. 

When any of these memory adjustments take place all the IOS pointers and the own memory addresses in 
the stream table entries are adjusted to remain correct. 

Notes. 

(1) The stream table and the own RAM areas аге кері in the same order, viz. that in which they were opened 
(providing MKBUFF is only called from OPEN routines). 


Fig. 5: Correspondence between stream table entries and own RAM allocation 
;——— , own memory for 
zd 


i. first stream. 


own memory for 
‘second stream 


(IOSRAM) 


‘own memory for 


as stream 


ТАТА stream table entry 
ишы! 4 for teat steam 


stream table entry 
L for second stream 


stream table entry 
ІШ for last stream 


(STRTOP) — 


(2) The device table can reasonably be kept in the IOS area 

(3) The naive programmer doesn'tneed to know anything about the IOS data structure when writing a device 
driver or calling an IOS routine, since it is entirely handled by IOS andaliparameters of interesttothe user are 
passed on. 

IOS Interface 

OPENIN and OPNOUT. Calling codes: 032Н, 0338, respectively. 


Call with driver number. 
port number 
stream number 
HL — parameter string 
BC length of parameter string 
On return 


DE, IX, IY and alternative registers preserved 
EUER. E clear, open succeeded 
BCHL = parameter string returned from device driver 
A destroyed 


он..... esel open failed- по stream table entry or own memory made 
BCHL destroyed 
A= error code 
BCHL are passed to and from the device driver and not looked а! by IOS. 
The stream number is checked against the stream table- Ihe open will fail i the stream is already open 
The port number is intended primarily as a parameter for the device driver. and is kept by IOS since 
subsequent calis to IOS INPUT, OUTPUT and CLOSE do not require it as а parameter. 
However, the pair consisting of the driver number and port number is checked against the stream table and if 
already present the open fails. 
Possible Error Codes 


подеу 106 по such device 

stropn 108 stream already open 

devopn 107 driver port pair already open 
погоот 100 insufficient memory to open 

тедет 109 105 routine not supported by device 


Other error codes may be generated by the device driver. 
INPUT, OUTPUT and CLOSE. Calling codes: 931 H, 30H, 234Н respectively. 


Call with Е = stream number 
A= data 

On return 

EITHER... deis CY clear, A = dala 

Ойы RUM CY set, A= error code 


In both cases BCDEHL and other registers preserved. 

The dala is passed to and from the device driver. 

Possible Error Codes 

nostrm 105 stream по! open 

тедет 109 105 routine not supported by device 

Other errors may be generated by the device driver. 

In the case of CLOSE the stream entry and own memory are closed whether or not an error occurred. 
Ef Calling code: 037H 


Call with BC- number bytes of own memory required (+ 9) 
Е = stream number 


On return 

EITHER .. РИЯ CY clear, HL — own memory 
A destroyed 

OR.. - sees. CY set, HL destroyed 


A= error code - no room (100) 
BCDE and other registers preserved. 
MKBUFF may only be cailed during the execution of the OPEN routine for the stream for which the own 
memory is being requested and oniy once during that routine. Because о! this restriction in the non-paged- 
memory operating system one device driver may not open or close another (though it may input from or 
‘output to it) 
MKBUFF will also crash the system if the stream number is incorrect or if the number of bytes requested is 
zero. 
Device Oriver Interface 
А device driver must start with a table of one byte displacements to its routines. The first entry in the table is 
the count, п, of the number of displacements - 1. The remaining (п +1) entries are the displacements. A 
displacements set lo zero to indicate no such routine is present IOS uses this table o! displacements to call 
the appropriate routine, the displacements are treated as unsigned eight bit numbers and each is added to. 
the address al which it is found to give the address of the routine. 


Example 

DDRIV: — EQUS$ ; a device driver 
DEFB 4 1 count of displacements- 1 
DEFB DOPNIN-$  ; displacement to OPENIN 
DEFB DOPNOU-$ displacement to OPNOUT 
DEFB DINP-S 1 displacement to INPUT 
DEFB DOUT-S | displacement to OUTPUT 


DEF 0С15-5 displacement to CLOSE 


DOPNIN: EQUS 2 OPENIN routine 


DOPNOU: EQUS 2 OPNOUT routine 


Routine Intertaces 

open in, open out 

Called with D= port number 
E = stream number 
BCHL- parameter string 


Return with 
EITHER: . e esst CY set, A= error code 
ORG stare CY clear ВСНІ = returned parameter sting 


The routines must preserve IY and alternative registers, but need not preserve the main registers or IX 
While the parameter string is only passed by 105 between the caller and the device driver, many NewBrain 
user programs attach a meaning to it, and so it should be returned as BC = 0 if not used 
input, output, close 
Called with data 

D = port number 

Е = stream number 

HL — own memory 


Return with 
EITHER .. CY clear, A= data 
OR CY set, A= error code 


These routines must preserve IY and alternative registers but need not preserve the main registers or 1X 


Compatibility with Paged Operating System 

The interfaces (between the user program and IOS via OPENIN, INPUT etc, and between 105 and device 
drivers, ie. the format of a device driver and Ine parameters for its routines, open, при. elc.) remain the same 
under PIOS. However the data structure (apart from device driver own-memory) is implemented differently. 
Routines are available to add device drivers to the system and to make status enquiries. Own memory is 
requested via MKBUFF, as before, but requests should be limited to a maximum of 8K. Parameter string 
lengths shouid be limited to a maximum 256 bytes. 
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Use of own memory by standard device drivers, ТР110, TP2IO, TVIO, ШО, TLIO, LPIO, JGIO, 
UPIO and DUMMY 

interface 

Device driver open routines call MKBUFF to allocate own memory to a device, the address ol this memory 
is passed to the device driver on calls to INPUT, OUTPUT and CLOSE. OPENIN and OPNOUT allocate a 
stream to the device, subsequent calls to INPUT, OUTPUT and CLOSE then reference the stream rather than 
the driver number and port number. On return from a CLOSE routine the stream and own memory area are 
deallocated by IOS. Own memory should not contain absolute addresses as CLOSEing one device may 
cause the own memory lor another device to be moved. Some devices, e 9. video, however, require to таке 
adjustments to the contents of own memory should it be moved. For these a sixth routine MOVE, is 
implementud with an entry in the device driver entry table. 

Cassette Drivers 

ТРИО driver number 1 

TP2IO driver number 2 

On open the parameter string is checked and the bulter size is added to the working storage requirement 
©! six bytes to give the total own memory requirement 


Low memory address 
. 018019, start of own memory area 


FLAGS 
8570 Butter length parameter, detault 4 
ВТЕМР ВСіѕ the countof bytes to process and gives the current position inthe 
СТЕМР data butter. 
TYPE Index number (see text) 
8 MOTOR Contains the COP motor contro! number of one of the two cassettes, 


(5-------сіке(6. start of buffer area 

5 (buffer size = buller length parameter * 256) 

High memory address 

The FLAGS location uses bits 9 and 7. Bit @ is set to suppress display of file names on the console stream 
during OPENIN. Bit 7 is the IN/OUT flag set to 9 by OPENIN and to 1 by OPENOUT. 

The index number TYPE is used on OUTPUT to write the block number to tape and on INPUT used to verity 
the block sequence. 

Display Editor Drivers 


ТМО Video display editor driver number 0 
LIO Vacuum fluorescent display (VF) editor driver number 3 
TUO Video display editor with concurrent VF display driver number 4 


No distinction is made between OPENIN and OPENOUT for these devices and once opened these devices 
тау be written to or read trom. 

In the discussion which follows the current ine" is Ihe tine in which the cursor currently rests (whether or not 
it is displayed). 

As well as keeping the own memory area up to date the editors use the fixed locations TVRAM, TVCUR, ТУЙ, 
TV! and TV2 1 communicate with the frame interrupt routine. 


0000 тур Video flash clock, 1 byte 
000E 152 Editor cursor flags, 1 byte 

9000 туї Character at cursor, 1 byte 

005A TVCUR Absolute address о! cursor, 2 bytes 

005C TVRAM Absolute address of current video own memory, 2 bytes 
TV2, the editor cursor flags, are used to control video dispiays 

Bit 

0-3 Reserved 

4 1 = Blank video for this frame only 


9- Cursor is character 127 
1 = Cursor is character 95 


6 1 Cursor currently displayed 
@ = Cursor not currently displayed 
7 @= Blank video 


Low memory address 


Offset to CSTO Й 
тумо1 j 
Accent 2 
ORDEP 3 
4 

DEP 
m 5 
EL 6 
т 
8 
9 
10 
11 
12 
13 
14 
15 


DSTO 


FLGSTO 
9 


Space 


High memory address 


TV mode value written to hardware video control register at each 
frame interrupt. 

Ассел) code for foreign language issue NewBrain editors. 
Origirai depth, no. of display lines heid in buffer. 

Depth, no. of display lines held in buffer excluding any high 
resolution graphics area. 

Line length, no. of display characters per line 

Excess line length, total bytes per line 

Flags 

Extra flags 

Line number, count of lines from top of display to current line. 
Frame, count о! lines within buffer lo first display tine (offset д) 
Window. по. of characters in current ine to start of 16 character VF 
window 

Initial В value at start of input line 

initial C value at start of input line 

Temporary storage 

Temporary storage 


For video devices with EXCESS 24, sufficiently many unused tocations 
to ensure that video buffer starts on a 128n+(LL/20) boundary 


Storage for registers 

C у coordinate] of the cursor within the current ine 
В x coordinate | (offset д) 

E character count of the last line of the current line 
D me number of tull screen lines in the current line 
Flag store 

Display butter 1st location 

Display butter 


End bytes 


The three Ilag locations are used as follows: 


Variable. Flag 

FLAGS SFTFLG 
IFLG 
CNSFLG 
CSIFLG 
XYFLG 
YFLG 


ESCFLG 
TVMFLG 
EXFLGS SNDCCFLG 
SNDXYFLG 
SNDYFLG 


CURSHOFLG 


FLGSTO TVFLG 
CHRFLG 
UFLG 
INPFLG 


Bit Indicates 
T 1 = Attribute оп 
в 1 = Insert mode 
5 This is the console device 
4 Reserved 
3 User sending cursor xy coordinates 
2 2- expecting x coordinate trom user 

1 = expecting y coordinate from user 
1 Escape mode 
0 Control W mode 
2 User has requested the character at cursor position 
6 
5 


User has requested xy coordinates of cursor 
= send x coordinate 
1 = send y coordinate 

4 Show cursor 

3-9 Reserved 

7 Driver supports video display 

6 Characters for sending in input mode 

5 Driver supports VF display 

4 Editor in input mode 


o 3 One line display set for VF and il deptn = 1 
PGEFLG 2 Page return mode 

HLDFLG 1 Hold mode 

CRFLG 0 Carriage return mode 


The values o! the registers may be shown graphically as follows: 


FLGSTO 
(usuai 
position 
o! HL 
pointer) 


8 | current line 


4 end bytes 


All cursor and memory positional information is held as offset zero. So if the cursor is positioned at the 
extreme left of the first line of the current line B and C contain zeros. The memory address of the cursor 
Position can be calculated from 

HL+LN*EL+B*EL+C+1 
where HL contains FLGSTO address, LN is the line number of the current line in the display butler (olfset 0) 
and EL is the total bytes per line, characters and excess. 
If B.C and LN are zero the result is HL 1. the first buffer location. 
Serial Device Drivers 
LPIO Software serial pnnter driver ы driver number 8 
JGIO Software serial general purpose bi-directional V24 driver number 9 


On open the parameter string is checked, BC is set to 4 and MKBUFF (make buffer) is called. The four bytes. 
of own memory are set up as follows: 


Receive Baud Rate Parameter 0 offset JGIO only ee 
Print Line Length set to 80 1 
[Print head position ілігу setto@) 2 LPIO ony 
__Transmit Baud Rate Parameter 3 


The value of the baud rate parameters is calculated by dividing the baud rate requested into the maximum 
allowed rate (19200). E.g. 9600 baud gives a baud rate parameter of 2. 


User Port 

ОРО driver number 7 

This driver inputs directly from and outputs directly to the 280 port specified on open. It does not use own 
memory. 

Dummy Device 

DUMMY driver number 10 


This device is intended for use in programs where I/O requests are made to a stream but for some reason no 
1/0 operations are required on that stream. It does not use own memory. 
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Patching a device driver 

This note explains how a new device driver may be patched into the NewBrain (unexpanded, іе. unpaged) 
operating system. Most of the note consists of an example: patching the software serial driver (JGIO) to 
receive 7-bit data with even parity instead of 8-bit data with no parity. To understand the note first read 
Technical Note 7 (IOS). To understand the example in detail reference must be made to the listing of JGIO. 
First the device table must be rewritten in RAM. An additional device driver may be added by increasing the 
entry count by one and adding to the end an additional entry being the address of the new device driver. 
Alternalively (as in the example below) an old device driver may be replaced by simply reassigning its device 
table entry to the address of the new driver. If the driver is 10 be in RAM to run under BASIC then memory 
space should be reserved for it and the appropriate machine code entered. Reassigning the fixed location 
DEVTAB to point to the new device table completes the patch. 

Example 

Page 2 is the Assembly code for the patched driver. 

Page 4 is the BASIC program which patches it in. 


ADDR СОЕ STMT SOURCE STATEMENT 
2001 PSECT ABS 
7C36 9002 ORG 31798 
E435 0003 JGOP. EQU QE435H 
E49A 0004 JGOUT EQU QE49AH 
Е4Е4 9005 JGIN EQU ФЕ4Е4Н 
7C36 04 9207 NJGIO DEFB 4 ; COUNT OF ENTRIES 
7637 05 0908 DEFB NJGOP-$ :ОРЕМ 
7С38 04 9209 DEFS NJGOP-$ 10РЕМ 
7639 ов 9010 DEFB NJGIN-$ ;INPUT. 
7C3A 05 9011 ОЕҒВ NJGOUT-$ — ;OUTPUT 
g 7638 07 8813 DEFBNJGCLS-$ :С105Е 
Ц 
ТСЭС C335E4 0014 NJGOP. JP JGOP. 
7C3F  C39AE4 0015 NJGOUT. — JPJGOUT ; USE OLD ROUTINES 
7042 B7 0016 NJGCLS: ORA 
7C43 С9 0017 RET 
2018 
7C44 СОЕ4Е4 09019 NO CALL JGIN ; COLLECT 8 BITS. 
7С47 87 0020 ORA : SET PARITY FLAGON CONTENTS 
FA 
7C48 EA4F7C 9021 ЈР PE NJ1 ; IF EVEN PARITY 
7C4B 3E96 0022 LD A, 150 ; ERROR CODE FOR ILLEGAL 
PARITY 
704 37 0923 SCF 
7C4E c 0924 RET ERROR RETURN 
0025 
7C4F СВВҒ 0926 NJ* ВЕ57,А ; CONVERT TO 7 BIT DATA 
9227 ELAY NOW FOR ONE BIT TIME 


1С51 4А 9028 10 C. D AUD RATE PARAMETER 
7C52 960C 0029 0 В, 12 
7С54 19ҒЕ 0030 NJ6: DJNZ NJ6 
7C56 — 0D 0031 NJ7: DECC 
7657 СВ 0232 ВЕТ2 : DELAY OVER 
7058 260Е 0933 108,14 
7С5А 1ЙҒЕ 0934 м8: DJNZ м8 
7650 18Ғ8 0935 ЈА NJ7 
9036 
0037 ЕМО 
ERRORS = 0000 


Тһе assembly code was produced оп а 2-80 cross assembler. 


The addresses JGOP, JGOUT апа JGIN have been found by examining the JGIO entry table indexed from 
the device table: 


0058 DEVTAB Address of Device Table 
For example: 
ме have PEEK (5 * 16+8)+256 * PEEK (5 * 16+8+1)= 41041 
So the device table is found at address 41041. JGIO is device 9 and 


PEEK (41041 +9*2+1)+256 "(41041 %9%2%-2)- 58415 
So the JGIO entry labie is at address 58415. СОР. JGIN and .GOUT are the second, third and fourth 
displacements in the entry table so the required addresses are. 
58415+2+РЕЕК (58415+2)= 58421 (06435) JGOP 
58415+3+PEEK (58415 +3) = 58596 (PE4E4H) JGIN 
58415+4+РЕЕК (58415 +4) = 58522 (QE49AH) JGOUT 
5 REM The foliowing BASIC program patches in the code and activates the new device driver: 
6 If TOP < 32000 then 30 
10 Reserve 998: REM reserve adequate RAM space for new driver and device table 
25 DEF FNnx(i) = PEEK (i) +256 * PEEK (i+1) 
30 di FNhx(88) REM DEVTAB pointer 
40 РОВ і= 0 ТО 24 :РОКЕ fo PEEK idt+ |) NEXT) REM copy device table to new location in RAM 
50 И= FNhx (ТОР+ 19): REM device table entry for JGIO = pointer to oid JGIO driver 
60 jg= TOP--30 REM location of new JGIO ariver 
70 POKE TOP «19, jg-INT (jg/256) * 256: POKE TOP 20 INT(jg/256! REM put location of new driver 
into device table 
80 RESTORE 100 2-90 
90 READ x$: IF x$ <> FOE ad. FNdiX$): ad = ad= 1 GOTO ge REM poke in new driver 
100 DATA 04. 05, 04. 0B. 05. 07. СЗ. 35. E4. C3. 9A. E4. B7. C9. CD Еа E4, B7. EA 4F. 7C. ЗЕ 96.37 СЧ 
CB. BF. åA. 06. QC. 10. FE. QD. C8. 06 QE. 10. FE. 18. FB. * 
105 REM hexadecimal conversion functions. 
110 DEF ЕМ) = 16 FN + FNd! (MIDSUS 2) 
120 DEF FNd1 (х$) = А$Сх$)< 55 AND ASC(XS}-48 ОЯ А5С05) > 57 АМО Ach 
130 POKE 88. TOP-INT(TOP/256) * 256: POKE 89, INT(TOP/256). REM activate лем device table 
140 END 
A shor! NewBrain BASIC program was wnitien 10 read the hexadecimal trom the cross assembler system. 
object file output via а V24 interlace into Ihe target NewBrain and to create the required DATA statements. 


__ Арш L ,.! 


Technical Note 10 Issue 1 NewBrain A/AD unexpanded 


Operating system routines 

The following list of calling codes describes the routines provided in the NewBrain operating system. They 
may be invoked by a machine code program using the instruction RST 32 (op. code Е7. decima! 231) 
followed by the calling code in the next byte- this is in contrast to using CALL followed by a two-byte 
address. They may also be invoked conditionally on the Carry flag being clear, using the instruction RST 40 
(op. code EF, decima! 239) followed by the calling code - in contrast to CALL NC. 


(A) Mathematics Routines 


The Maths Pack routines are principally distinguished by the number of operands required. Those which 
have no operands are designated MO, and load the relevant value directly into the Floating Point 
Accumulator, or FACC, in the Maths Pack working area. Those designated M1 require one parameter, іп the 
FACC, and return a result in the FACC. M2 routines need two parameters; the first is found in the FACC and 
the second is the six-byte floating point number whose lowest byte has ils address in DE when the routine is 
invoked. The remaining Maths routines һауе special requirements, and are designated MS; they include 
routines to load and store the FACC area using numbers in 6-byte floating point format, 16-bit positive 
integer format, or ASCII string format. 

‘An extra interface is provided to tne Maths routines via the special calling code ZMATHS. This is especially 
appropriate for use by programs such as BASIC, which require a stack of working operands. The MATHS 
routine is invoked by RST 32 or RST 40 with a Maths code in the A register and the HL register pair printing o 
a stack area. The Maths code, which is given after the designation lor MO, М1 and M2 routines, is used as a 
Telerence to one of those routines. I tis an MO routine, the HL register pair is decreased by 6 and the result 
stored where it then points. For an М1 routine, HL points to the operand and the result is stored in the same 
piace. For an M2 routine, HL points to the second operand when the MATHS routine is invoked, and the first 
operand is at(H\ +6); the result is stored in the latter location. In each case, on exit, HL points io the result. 
If any routine encounters an error, the Carry flat will be set. Where any registers are preserved, they are listed 
in parentheses after the designation, with “F” representing the РАСС. On exit from a routine designated MO, 
МТ or M2, HL points lo the РАСС. 


Calling code Designation 
and 

Hex Decimal Мате Maths code Result 

00 0 ZRND M0:00 random number 

01 1 ZP: M0:02 constant- pi 

02 2 25ТРО5 140.04 print head position (гот RAM location PHPOS) 

03 3 ZFPONE M0:06 constant- опе 

04 4 ZFPMONE М0:08 constant - minus one 

05 5 ZFPZERO МО:0А constant - zero 

06 6 ZNOP M1:80(F) то action 

07 7 ZNEG M1 :82 change sign if non-zero 

08 8 ZNOT М1:84 logical NOT* 

09 9 ZABS M1:86 absolute value 

OA 10 ZATAN M1:88 arc tangent 

ов 11 Zcos М1:ВА cosine 

oc 12 ZEXP M1:8C exponential function (e raised to the power) 

90 13 ZINT М1:ВЕ greatest integer less than or equal to 

OE 14 ZLOG M1:90 natural logarithm 

[3 15 ZSIGN M1:90 sign: +1,0 or —1 

10 16 ZSIN M1:94 sine 

11 17 ZSQRT M1:96 Square root 

12 18 ZTAN M198 tangent 

13 19 ZASIN M1:9A arc sine 

14 20 ZACOS M1:9C arc cosine 

15 21 ZPEEK М1:9Е value of the byte found at the memory address 
given by the operand 

16 22 ZADD M2:40 sum 

17 23 2508 M2:42 first operand- second operand 

18 24 ZMULT M2:44 product 

19 25 20% М2:46 first operand divided by second operand 

1А 26 ZRAISE M2:48 first operand raised 10 the power ol second 
орегала 

18 27 ZAND M2:4A logical AND* 

10 28 ZOR M2:4C logica! OR" 

10 29 ZNUMEQ | M24E TRUE if the operands have the same value; 


FALSE otherwise 


iF з 
20 32 
А] зз 
22 34 
23 25 
24 36 
25 37 
26 зв 
27 39 
28 40 
29 а 
2А 42 
28 43 
2с 44 
20 45 
2E 46 
3E 62 
ЗЕ 63 
40 64 


ZNUMGT 
ZNUMLT 
ZNUMNE 
ZNUMLE 
ZNUMGE 
ZMATHS 


ZINITRAND. 
ZRANDOM 
ZCOMP 


ZFIX 
287 


ZROUND 
ZINP 


ZLOF 
тойт 


257Ғ 
2RE.800 
ZFPHLF 


2ЕРІ02 
ZBICML 


M2:50 
M2:52 
M2:54 
M2:56 
M2:58 
MS 


) 
s (Fi 
us 


м5 
м5 


MS 
MS 


MS{BCHL) 
м5 


MS;BCHLF) 
vs 


м5 
м5 
м5 


TRUE й first operand greater than the second; 
FALSE otherwise 

TRUE if first operand less than the second; 
FALSE otherwise 

TRUE if operands do по! nave the same value, 
FALSE otherwise 

TRUE if first operand is less than or equal to the 
second: FALSE otherwise 

TRUE i the first operand is greater than or equal 
10 the second. FALSE otherwise 

loads the FACC trom value addressed by HL. 
sets DE. and catis appropriate MO, М1 or М2 
routine, given by Maths code in A, then stores 
result CY set and A=2 if error. 

the random number generator is set lo a 
‘standard value 

the random number generator is sel to the value 
of the 4 byte page zero location CLOCK 

CY is set i first operand (HL) greater than the 
Second (DE). clear otherwise. Zero flag is sel if 
operands are equal 

operand addressed by HLis converted to 16-bit 
positive binary and returned in DE 

16-bit positive binary value in DE is converted to 
floating point in the FACC HL points to the 
FACC 

contents of the FACC are increased by 05 and 
converted to 16-bit positive binary in DE 
ASCII string referenced by DE is converted to 
floating point, fitis a number. DE is setto the first 
unused character, HL to the FACC 

floating point number addressed by HL is 
loaded into the ҒАСС 

value in the FACC is converted to an ASCII 
sting in the Maths pack working area, using BC. 
as the format code.** HL is left pointing to the 
string, with С = number of characters 
contents of the FACC are copied into the location 
addressed by HL 

examines Сату and Zero flag and returns TRUE 
or FALSE. Enter with bit 0 of B sel if NC, NZ 
should yield TRUE; bit seti C, NZ should yield 
TRUE. avd bi! 2 set if Z should yield TRUE 
co^stant- halt 

constant- half of pi 

converts value in the FACC to integer part in DE 
‘and most significant мо bytes of fractional part 
in ВС, CY set if overtiow, 2 set if positive, NZ i 
negative 


* The logical operations NOT, AND, OR first convert the operand or operands to 16-bit twos complement 
numbers in the range —32768 to +32767. If this cannot be done an error is returned. A bitwise logical 
‘operation is then performed and the result is floated into the FACC. 

5" The format coding in MC specifies the format type "f" in bits 6. 7 of B. Ihe number о! digits "i" for the 
integer part in bits 0-5 of B and the total digit count "t" in C. as shown below. It the format is inappropriate. 
the string returned by ZOUT will contain asterisks on overflow or periods on undertiow. 


t=0 


1=2 


Fixed point format 


Number is rounded to decimal with t digits, 1 decimal places. Leading zeros 
represented as spaces, 1 leading space or minus sign. 1 trailing space. Total field width 
1+3 except when t= i (integer format). 1+2. 


Free format 


Number is rounded to t significant figures and output in fixed or exponential format- 
goes to exponential above 10' er below 10-3. Underflows are converted to ASCII 2. 
The field width is variable. 


Exponential format 


Number is output as for fixed point format with two digit exponent: total field width t 7. 


For all formats must have 102 t» i» Q. 

(B) Operating System and Input- Output System Routines 

Шап error is encountered, the Carry flag is set and the A register contains an error number. Some routines 
always return with Carry clear; for others (e.g. TTCAPS) the Carry flat does not denote an error 

Calling code 


Hex Decimal Мате Registers Details 
2F 47 ZTTCAPS BCDEHL Byte in A, if itis "a" to“z”, is converted to capital 
"A" lo -Z" 
30 48 ZOUTPUT BCDEHL Entry: А- data byte. 
E = stream number 
31 49 ZINPUT BCOEHL Entry: E= stream number 
Екі: A= data byte il CY clear 
32 50 ZOPENIN ОЕ Open stream for input. 


Entry: A = driver number 

D= роп number, E = stream number, 
ВС- parameter string length 

HL = start of parameter string. 

Ext: BC, НІ = parameter string returned 


33 5) ZOPENOUT DE Open stream for output, as OPENIN 
34 52 2CLOSE DEHL Ciose stream 
Entry: Е = stream number 
35 53 ZSTKTST [1 Checks if remaining stack space is large enough 


Entry: BC = number of bytes 
Exit: CY setif insufficient room left on stack to 


add BC bytes. 
36 54 ZBRKTST | BCDEHL Checks and clears the STOP key tlag 
Exit: if STOP key pressed, A = 0 and CY set 
37 55 ZMKBUFF BCDE Creates an own memory area in IOS space о! 
BC bytes. 


Entry: 8С = number of bytes required 
Е = stream number 
Exit: if CY clear, HL points to start of own 
memory area provided 
Note: MKBUFF may only be called by a device 
driver during OPEN, and should only be 
called once! 
38 56 ZGETKEY попе Gets a byte of coded keyboard data from the 
COP. 280 may power down during GETKEY 
Exit: A= data byte containing keyboard matrix 
coordinate 
39 57 ZIMMKEY BCDE Gels a byte of coded keyboard data from the 
COP il one is available 
Exit: CY clear, A= dala byte as GETKEY 
CY set if no dala byte available. 
3A 58 ZKLOOK DE Converts keyboard matrix coordinate to ASCII 
ог graphics character 
Епігу: A= keyboard matrix coordinate 
Exit: A= character 
Note: Page zero location КВМОПЕ is used to 
determine any currently in or keyboard 
attributes 
зв 59 ZFSTRM ABCDE Finds a matching stream number 
Entry: E= stream number 
Exit: CY clear, HL points to stream table entry 
at offset 0 
зс 60 ZBLKIN DE Inputs а block of bytes from a stream into 


number of bytes 

first memory location 

E=stream number 

Ext: Су clear, BC=0, HL increased by BC 
СҮ set. BC= number of bytes not input, 
HL increased by the number о! bytes 
input 


Calling code 


Hex Decimal 
30 61 
41 65 
42 66 
43 67 


Мате 
ZBLKOUT 


ZROBYTE 


ZRDINT 


ZRDNSP 


Registers 
DE 


BDE 


BDE 


Detaiis 
Outputs a block of bytes from a memory area 
Entry: BC= number of bytes 


HL first memory location. 
Exit: CY clear, BC=0, HL increased by ВС 
CY set, BC= number о! bytes not output 
HL increased by number of bytes output 
Converts an ASCII string or substring to an 8-bit 
integer 
Entry: C= string character count 
L- location of first character of string, 
with subsequent characters al 
higher addresses. 
Exit: C=count on entry less number of 
numeric characters read 
A= binary integer 
HL= address following address of last 
numeric character read 
CY set if overflow or non-numeric 
Converts an ASCII string or substring to a 16-bit 
integer 
Entry: as for ROBYTE 
Exit: C, HL as for RDBYTE 
DE = binary integer 
Scans a string for a non-space character 
Entry. as for ROBYTE. 
Ext: 2 flag set if count C exhausted 
НІ = address of first non-space charac- 
ler found 
C= count of characters remaining 
A= first_non-space character found, 
"до 2 iit 
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Access to screen display characters 

The NewBrain screen editor provides facilities to enable a user to find characters sited anywhere on the 
display screen and to place characters directly on to the screen in selected positions. This is done using the 
control codes detailed below, which may be output to any TV stream using PUT in a BASIC command line or 
program. 


Position cursor at xy PUT22xy 

Place a characler c al position ху PUT 22%, 

Find out what character is at position xy PUT 22ху20: GET c 
move cursor to HOME (1,1) PUT 12 

Move cursor up one (it possible) PUT! 

Move cursor down one (if possible) PUT 10 

Move cursor telt one (if possible) PUTS 

Move cursor right one (if possible) PUT 26 

Find cursor position PUT 21: GET xy 


The entire line on which the cursor is positioned may be obtained using 
PUT 5: UN fas 


The entire screen area may be obtained, for instance to сору it to another stream, by a sequence of 
statements: 


PUT 3: FOR |=1 to 24: LINPUT ("") aS:....: NEXT I 


Enough LINPUT commands must be executed to allow for every line of the screen. 

Example: To check if the character to the right of position (p.q) is a blank, and if so move the character at 
position (p.g) one to the right 

PUT 22, p+ 1.q: GET C 

IF c= 32 THEN PUT 8, 20; GET c: PUT 32, c; p= p+! 


The cursor is positioned one to the right of (p.a) and the character at that position obtained (c). It it is a 
blank (code 32), the cursor is moved one to the e and the character code which was there is obtained 
(с again). A blank 15 written, which moves the cursor one to the right, followed by the characler с. 

While instructions of this sort are being processed, the cursor will not normally be shown. If it is desirable to 
show the cursor, e.g. while developing programs, contro! code 6 may be PUT to the screen. The cursor will 
then be displayed at all limes until control code 7 is PUT. 

The control codes 3, 5, 20 and 21 cause the screen driver to expect one or more calls of GET, INPUT, or 
LINPUT. It will go on expecting such calls until either the right number of characters have been returned, or 
any byte is PUT to the screen. E.g. to copy Ihe first 5 lines of the screen lo a printer: 

OPEN 4 2,8: PUT 3 

FOR I= 1 to 5: LINPUT # 0, a$: PRINT # 2, a$: NEXT | 

PUT 0: REM cancels effect of PUT 3 


When LINPUT is used inthis way. the default prompt"?-" must be suppressed by using the form LINPUT 4 s, 
a$ or LINPUT as Otherwise, the prompt which is output to the screen cancels the "send" mode and 
Causes the program to enter the usual keyboard input mode. 


AE ‚/@ / 
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NewBrain BASIC reserved words 


NewBrain BASIC reserved words are entokened. The same token may be used for two different words, 
meaning being oblained from word order. 

eg. PRINT А5С 

has character 131 then character 158, PRINT POKE being illegal 

Entokened words in the range 128 10 158 can be input by using the GRAPHICS key For those in Ihe range 
16010187 itis necessary for" CONTROL 4" (5, 6 or 7) to be entered first, then use the GRAPHICS key with Ihe. 
character in the table. This gives you the secondary-graphics mode, hence the "2" shown in the lable. 
The odd one out is character 159 (CALL or LEN). This first requires attributes on (уре CONTROL N), then 
type ESCAPE followed by SHIFT HOME. Don't forget to turn the attributes off (SHIFT/ESCAPE) 


NewBrain Reserved Words Table 


Token “GRAPHICS” Token "GRAPHICS" 
value аға value and 
128 LET NOT = 159 CALL LEN ATT* 
199 LIST * А SHIFT 
130 NEW - в НОМЕ 
131 PRINT * C 160 CONTINUE VAL 22 
132 RUN / D 161 DEF NUM 2A 
133 GOTO - Е 162 CLEAR ASN 28 
134 GOTO . F 163 MERGE ACS 2c 
135  GOSUB AND 8 164 — VERIFY PEEK 20 
136 GO SUB H 165 GET ERRNO 2E 
137 IF П 166 RESUME INSTR — 2F 
138 INPUT J 167 DELETE ERRLIN 26 
139 FOR K 168 807 TOP 2H 
140 NEXT - L 169 LINPUT FREE 2! 
141 RETURN > м 170 REPORT CHAS 21 
142 REM < N 171 CONT 5185 2K 
143 ЕМО ямо 0 172 RESERVE RIGHTS 21 
144 STOP Р! Р 173 FILES 2M 
145 DIM POS 0 174 LEFT$ 2 
146 ON ABS R 1% MIDS 20 
147 OPTION АТМ 5 176 BASE 2Р 
148 SAVE соз T 177 INe 20 
149 LOAD EXP. у 178 ола 28 
150 RANDOMIZE INT у 179 . 25 
151 OPEN LoG w 180 THEN 2T 
152 CLOSE SGN X 181 Invisible THEN 20 
153 ? SIN Y 182 TO 2v 
154 RET боя 2 183 5ТЕР 2W 
155 RESTORE TAN ( 184 FN 2х 
156 READ TRUE 185 TAB 2Y 
157 DATA FALSE) 186 ERROR 22 
158 POKE ASC * 187 BREAK 2ʃ 


* ATT is CONTROL N (attributes on) 
** "2" means secondary graphics CONTROL 4 (5, 6 or 7) 


NewBrain BASIC Reserved Words Table 


Token Keyboard sequence. Character Character. 

BASIC value "GRAPHICS" апа sel! set2 
ABS 146 R [1 

ACS 163 2c y 

AND 135 в F 
ASC 158 * e қ 
ASN 162 2B ü B 

ATN 147 5 ч 

ВАЗЕ 176 2P g 


BREAK 187 E n © 


Токеп Keyboard sequence Character Character 
BASIC value GRAPHICS" апа sett set2 
CALL 159 ATT SHIFT HOME 
CHR$ 170 2) 
CLEAR 162 2B 
CLOSE 152 x 
CONT 171 ?к 
CONTINUE 160 2- 
cos 148 T 
DATA 157 ) 
DEF 161 2А 
DELETE 167 25 
ом 145 а 
END 143 o 
ERRLIN 167 26 
ERRNO 165 2E 
ERROR 186 22 
ЕХР 149 о 
FALSE 157 ) 
FILES 173 2M 
FN 184 2x 
FOR 139 к 
ЕВЕЕ 169 2 
бЕТ 165 2E 
GO SUB 136 
вото 134 ғ 
GOSUB 135 © 
вото 133 E 
IF 137 1 
INE 177 20 
INPUT 138 J 
INSTR 166 2ғ 
INT 150 v 
LEFTS 174 2N 
LEN 159 АТТ SHIFT HOME 
LET 128 
LINPUT 169 2i 
ust 129 А 
LOAD 149 u 
LOG 151 w 
MERGE 163 2c 
MIDS 175 20 


Токеп Keyboard sequence Character Character 


BASIC — маше GRAPHICS" апа зегі set2 
NEW 130 в 
NEXT 140 L 
NOT 128 - 
NUM 161 2A 
ON 146 R 
OPEN 151 w 
OPTION 147 s 
OR 136 H 
OUT# 178 2R 
РЕЕК 164 20 
PI 144 e 
POKE 158 + 
POS 145 о 
PRINT 131 с 
PUT 168 2H 
RANDOMIZE 150 v 
READ 156 
REM 142 
REPORT 170 20 
RESERVE 172 24 
RESTORE 155 ( 
RESUME 166 2ғ 
НЕТ 154 2 
RETURN тат м 
RIGHTS 172 2L 
RND 143 о 
RUN 132 D 
SAVE 148 T 
SGN 152 x 
SIN 153 Y 
SOR 154 2 
STEP 183 2w 
STOP 144 Р 
STR$ 171 2K 
ТАВ 185 av 
TAN 155 t 
THEN 180 ar 
THEN (invisible) 181 20 
то 182 2% 


ТОР 168 2н 


Токеп Keyboard sequence Character Character 
BASIC value "GRAPHICS" and sett $е!2 
- 
TRUE 156 
VAL 160 2- 
VERIFY 164 20 
+ 179 25 
& 134 F 
Ы 131 с 
+ 129 A 
= 130 в 
/ 132 0 
< 142 N 
- 140 t 
> 141 M 
? 153 
. 133 
<> 137 ' 
<- 138 J 
>= 139 к 
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Keyboard sequences 

Ай 256 characters of the NewBrain character set are obtainable from the keyboard. Mode group 1 is 
graphics-shift(corresponding to CONTROL 2, 3,6, 7, 8 or9, ie. press CONTROL key and "2" simultaneously). 
Mode group 2 is secondary-graphics (CONTROL 4, 5. 6 or 7) and mode group 3 is tertiary-graphics 


(CONTROL 8 or 9). 

In the table the following keys are denoted 
cnt lor CONTROL 

sh for SHIFT 

grph for GRAPHICS 

АТТ for CONTROL М {attributes оп) 


cursor LEFT for = 

cursor UP — fort 

cursor DOWN for i. 

Cursor RIGHT for — 

Some characters can be obtained in more than one way, these sequences are separated by a comma. 
The character shown in brackets corresponds to character set 2. 

Mode group 1 (Shift keys 224-254 contro! 2, 3, 6...9) 

Mode group 2 (Graph keys 161-254 control 4...7) 

Mode group 3 (Graph keys 192-222 control 8, 9) 


0 cnt/- 29 cnl/CURSOR RIGHT dn 
3 cnt/Ash/INSERT 30 cnti/+,cnti/HOME оар 
2 cnt/B.sh/CURSOR DOWN 31 sh/HOME ж 
3 onti/C,cntl/NEW LINE 32 SPACE BAR e 
4 cnt/D 33 shit 1218) 
5 ст/Е 34 shi2 qo 
6 стуғ 35 sh/3 (#) 
7 смуб 36 sh/4 (+) 
8 cnti/H,CURSOR LEFT 37 sh/S (Ж) 
9 cnlil/lcntI/ESCAPE 38 sh/6 (&) 
10 cnt/J|CURSOR DOWN 39 sh/7 €^) 
1! cntl/K,CURSOR UP 40 sh/8 (C) 
12 cn'/LHOME 41 sh/9) (>) 
13 cntl/M,sh/NEW LINE, NEW LINE 42° E 
14 entl/N,sh/CURSOR UP 43 + (+) 
15 cntl/O,sh/ESCAPE 4a, G39 
16 cn h/ ESC grph/NEWLINE 45 — (-) 
17 cnti/QINSERT 46 txt 
18 cntl/Rgrph/CURSOR UP 47 1 (4) 
19 enti/S.grph/CURSOR DOWN 48 0 Lu 
20 cnt/Tgrph/HOME 49 1 (1) 
21 cntl/Ugrph/INSERT 50 2 (2) 
22 onti/V.enti/INSERT 513 (3) 
23 спім 52 4 (4) 
24 cnt/Xsh/CURSOR LEFT 53 5 (5) 
25 enti/Y,sh/CURSOR RIGHT 54 6 (5) 
26 cntl/Z,CURSOR RIGHT 55 7 (7) 
27 спїДЕЗСАРЕ 56 8 ЕЗІ) 
28 cnt/-cnl/CURSOR LEFT 579 (9 


oO 146 grph/R 


58 85% (2) 102 F 

59 ; (a) 103 6 ЕЙ 147 os 
60 sh, (<) 104 н tho 148 grph/T 
81 * (=) 105 | ti) 148 агро 
62 sh. (>) 106 J сі» 150 grphv 
63 80% (t) 107 к tk) 151 grph/w 
64 sh/= (3) 108 L (o 152 grph/X 
65 sh/A (n 109 м (т) 153 grph/Y 
66 sh/B (e по N (ni 154 отрһ/2 
67 sh/C (с) "o о! 155 grph/( 
68 sh/D D 112 Р (p 156 grph/- 
69 sh/E (E! пз 0 (4) 157 grph/) 
70 sh/F (Р) 114 я (г) 158 grph/+ 
т 8% Тез) 115 5 (5) 159 ATT/sh/HOME 
72 sh/H (H? 116 т (t) 160 2/grph/= 
73 shi Oo ити u) 161 2/grph/A 
74 shid [Ир n8 v (v) 162 2/grph/B 
75 мк (o тө м (ш) 163 2/grpn/C 
76 м. (L) 120 X (х) 164 2/grph/D 
77 sh/M (M) 121 Y og) 165 2/grph/E 
78 sh/N (N) 122 2 (2) 166 2/grph/F 
79 sh/O (e 123 grph/, (0 167 2/grph/G 
80 sh/P (Р) 124 сту. 8%; 168 2/grph/H 
81 sh/Q (e 125 grph/. CU 169 2/grph/l 
82 sh/R (RO 126 grph// о» 170 2/grph/J 
83 sh/S БЇ 127 сту, 12 171 2/grph/K 
84 sh/T (T 128 grph/- E 172 2/grph/L 
85 shu an 129 grph/A -. 173 2/grph/M 
86 sh от 130 grph/B (b 174 2/grph/N 
87 shw I 131 grph/C ep 175 2/grph/O 
88 shn/X ) 132 grph/D id) 176 2/grph/P 
89 shy сү» 133 оғрһ/Е (T 177 2/grph/Q 
90 sh/z (2) 134 grph/F e 178 2/groh/R 
91 shi (p 135 grph/G (p 179 2/grph/S 
92 sh (М) 136 grph/H 180 2/gro^/T 
93 sh) B 137 grph/ 181 2/grph/U 
94 sh/* Ct) 188 grph/j 182 2/grph/V 
95 shWIDEO ТЕХТ = 139 grph/K 183 2/grph/W 
96 grph/ C) 140 grph/L 184 2/grph/X 
97 A (a) 141 рым 185 2/grph/Y 
98 8 ib) 142 grph/N 186 2/grph/Z 
99 C ( 143 grph/O 187 2/grph/t 
100 0 (di 144 grph/P 188 2/grph/- 
101 е (а) 145 стрмо 189 2% 


210 


24 
215 
26 
217 
218 
219 
220 
221 

222 
223 
224 
225 
226 
227 
228 
229 
230 
231 

232 
233 


2/grph/* 
A 
3/дтрл/= sh/o 
3/grph/A cnt; 
3/grph/B.cntl// 
3S/grph/C.grph// 
3/grph/D 
S/grph/E 
3/grph/F 
3/grph/G 
3/grph/H 
3/grph/i 
3/grph/J 
3/grph/K 
3/grph/L. 
3/grph/M 
S/groh/N 
3/grph/O 
3/grph/P 
З/армО 
3/grph/R. 
3/grph/S 
S/grph/T 
3/grph/U 
3/gronv 
3/gron/W 
3/grph/X 
S/grph/Y 
S/grph/z 
S/grph/t 
3/grph/- 
З/огрт/) 
3/grph/+ 
ATT/Sh/VIDEO TEXT 
T/sh/- 

Y/sh/A. 

T/sh/B. 

7600 
1/sh/D.sh/* 
ee 

1/8Һ/Ғ 

1/sh/G 
V/sh/H 

1/sh/l 


255 


1/өһ/) 
мук 
1/зһЛ. 
T/Sh/M 
1/sh/N 
1/sh/O 
1/sh/P 
ШУ») 
T/sh/R 
1/sh/S 
1/sh/T 
1/sh/U 
1s 
Y/sh/W 
Y/sh/X 
1/sh/Y 
1/sh/Z 
76 
1/67 
1/8һ/ 
T/sh/ 
ATT/cntl/, 


(%) 


Ae. t 
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NewBrain BASIC - Technical specification 

1 DATATYPES 

17 Numbers 

These are handied by the mathematics package. 

1.4.1 Storage Six bytes are allocated by BASIC lor the storage of a number value. The mathematics 

package maintains and operates on numbers юа precision of 10 or more significant figures in a range of 

£10800 

1.12 Output By default output is rounded to 8 significant figures and is in free format (integer, floating 

point or scientific “E” notation according to value) Outputto specific field sizes and formats can be forced by 

format specifiers for tne PRINT statement and the STRS function. Output range is 0.102%, 

1.13 Input Any output format is accepted as input, additionally any number of digits is allowed in the 

mantissa and spaces may be disregarded. 

1.1.4 Constants Any number valid lor input may be used as a numerica! constant 

115 Variables Any simple name consisting of a letter or a letter followed by a letter or a digit may be used 

to denote numeric variables. A variable may hold any valid number. 

12 Strings 

In NewBrain BASICa stringis any sequence of bytes (ie. numbers in Ihe rangeO. 2580 Bytes often stand for 

characters, in particular those in the range 32.. 127 stand for the ASCII printing characters. 

121 Storage Strings can be of any length between 0 and 32767 bytes. An additional overhead of four 

bytes is required for each string stored. Storage allocation is dynamic (е. the length of a string can change 

during program or command execution). 

122 Output Any string can be oulput Input and output devices interpret bytes in different ways. For 

instance the keyboard screen editor device, which is usually the console юг BASIC, interprets 0..31 as 

control codes, 32. 127 as ASCII character codes and 128..255 as mosaic graphics character codes. 
- 123 Input Any valid string constant may be supplied in response to a BASIC INPUT or READ statement. 

it the constant does not contain quotation marks (7), commas or TAB (code 09) characters the enclosing 

quotation marks may be omitted. Comma and TAB characters are used by INPUT to separate consecutive 

strings. In response to LINPUT any string not containing NEWLINE (code 13) character may be supplied. 

124 Constants Any string not containing a NEWLINE character may be enclosed in quotation marks (") 

and used as a string constant ina BASIC statement. Quotation marks within a string constant are denoted by 

doubled quotation marks () 

125 Variables Any simple name followed by a dollar (6) character may be used as a string variable 

name. A string variable may hoid any string. 

13 Logical 

There is no specia! logical datatype, but numbers may be used lo store logical values. In Ihose cases where 

a logical value is required for a binary choice, — is taken as TRUE and all other values are taken as FALSE. 

Logical operations are performed bitwise ол 16-bit words. In this sense — 1 is TRUE. is FALSE and other 

values from the range —32768. 32767 take intermediate truth value; some operations require arguments 

from this subrange. 

14 Arrays 

Arrays may be of numbers or strings, of 1 or 2 dimensions to a maximum of 5575 elements. Array storage 

must be reserved by DIMensioning, but each element of a string array may vary in length during program or 

command execution. In addition Io the storage required lor the values of the elements there is a storage 

Overhead of 6 bytes for an array and a further overhead of 2 bytes per element for a string array. 

There is no provision for input/output of whole arrays. 

Individual array elements may be treated the same way as numeric and string scalars for input/output. 

There are no array constants. 

Any number (or string) variable name may be used for a numeric (or string) array. A variable name thus used 

may also be used for a scalar of the same type. but may not be used for another array of the other dimension. 


2 EXPRESSIONS 


21 Atomic Expressions 
The allowed atomic expressions are 
constant variable name атау element function сай 


22 Molecular Expressions 
Atomic expressions may be built up to form molecular expressions. 


if X and Y are valid atomic expressions then 
Unaryoperaton X X binary operation 0 
аге valid molecular expressions subject lo the type restrictions detailed below. 
Constant This may be о! any string or number constant. 
Variable Name This may be any string or number variable name 
Array Element This із 
array name (expression) оғ атау name (expression, expression) 


The expressions involved must evaluate to numbers within the dimensions of the array. Numbers are 
founded to the nearest whole number for this purpose. 


Function Сай The genera! torm is. 
function name (arguments) 


The number and type о! arguments depends on the function, given this, an argument can be any expression 
ol the correct type. Arguments are separated by commas. 


22. Functions with No Arguments 


РІ The mathematical constant 

RND А pseudo-random number trom the uniform distribution of the unit interval (0.1) 
POS The current position of the printhead on the console output device 

TRUE Evaluates always 10 1 

FALSE Evaluates always to 0 

ERRNO The error number of the most recent error or break-in unless cleared 

ERRLIN The line number ot line being executed at the time of the most recent error or break-in 
FREE The number of bytes of tree store available to but not used by BASIC 

TOP The lowest store address not available to BASIC 

FILES The parameter string returned by the most recently OPENed input device 

222 Functions with One Numeric Argument 

INT Integer part (INT(X) is the greatest integer not greater than (X) 

ABS Absolute value (modulus) 

SGN Sign (-1 for negative argument, 1 tor positive, 0 tor zero} 

SOR Square root 


SIN COS ТАМ Trigonometric tunctions 
ASN ACS ATN inverse trigonometric functions 


LOG Natural logarithm: 

EXP Exponential function 

PEEK Contents of memory location whose address is the argument 

CHR$ The strong consisting of the single character whose internal code is the argument 
STRS The string consisting of the numeric output format of the argument 


The format may be forced. The expression STRS (Xiformatter)) produces a string inthe 
format determined by the formatter. Allowed formatters are: 
п Integer format with п digits 
am, Fixed point format with n digits belore and m after the point 
mE Scientific format with n digits before the point, m after and 2-digit exponent a 
multipie of n 
nF Free format in a field width of n 
їп all formats leading zeroes in the mantissa are replaced by spaces, there is a 
leading space or minus sign and a trailing space. 
223 Numeric Valued Functions with One String Argument 


LEN Length of the string 

VAL 110 numeric value of the string, if the string happens to be in а valid number input 
format 

NUM = —1 (TRUE) if the string happens to be in a valid number input format 
9 (FALSE) otherwise 

ASC The NewBrain internal code for the first character of the string (for characters in the 


ASCII set this coincides with the ASCII code) 
2.2.4 Substring Functions 


LEFTS LEFTS {X$.N) extracts the leftmost N character substring 

RIGHTS RIGHTS XS.N) extracts the rightmost N character substring 

MIDS MIDS (Х$.Р} extracts the right hand substring starting al the P'th character о! X$ 
MIDS (ХЅ,Р №; extracts the substring of length N starting at character Р 

INSTR INSTRIXS.Y$; finds the numerical position of the string Y$ in X$ 


INSTR(XS.YS,P} finds Ihe position in MIDS(XS.P) 
225 User Defined Functions These сте numeric or string valued with one or no numeric or string 
argument. A user defined function name is a simple name preceded by FN. User defined functions must be 


declared equal to an expression in а DEF statement 
226 Unary Operations These all lake numenc arguments and yield numeric results. 


7. — unary plus and minus 

NOT The bitwise Boolean operation 

227 Binary Operations with Numeric Arguments which Yield Numeric Results 

+ a Plus minus times divide 

' Raise 10 a power 

€ <= - Relations! operators. 

> o» <> {less than. less than or equal, equal. greater than. greater than or equal. по! equal) 

AND OR The bitwise Boolean operations 

228 Binary Operations with String Arguments which Yield Numeric Results 

< < - Relational operators returning Boolean results as in the numeric case. 

> >= <> Characters are ordered according to the NewBrain internal codes "wich ordenng 
agrees with ASCII and hence with alphabetic order) and strings are ordered by first 
dMterence. 

229 Binary Operations with String Arguments which Yield String Results 

+ (аво 8) Concatenation 


23 Expression Evaluation 


Within an expression atomic expressions and expressions i parentheses are evaluated lirst Operations are 
evaluated in Ihe order 


4 (unary operations) 
1 

* | 

^ & ibinary operations) 

NOT 

AND 

OR OR having the e binding power 


Mathematical operations and functions are evaluated by the mathematics package. The mathematics 
package has heen specially designed to minimise cumulative rounding errors and mamtain stability in 
recursive and iteralive calculation. and lo obtain maximal computation speed consistent with ten significant 
figure accuracy and long term stability. 


3 INPUT/OUTPUT 
This is perlormed by the NewBrain operating system. 


31 1/0 Devices 
1/0 devices are signihed by whole numbers in the range 0 to 255 in practice in а program, devices are 
usually named as питепс variables whose values signily the device. All input/output peripherals are 
configured by their device drivers as byte senai devices. 
32 DataStreams 
Data streams are signilied by whole numbers in the range 0 to 255. though in practice numeric уапаме 
names are used. In BASIC. alter opening a device on a datastream all communication with that device is via 
the datastream When appropriate devices and device dnvers are connected. appropriate control 
datastreams can be used 10 implement ай current 1/0 modes including random access. 
4 BASIC STATEMENTS. BLOCKS AND PROGRAMS 
ABASIC statement generally consists o! a keyword followed by certain arguments. A BASIC line consists o! 
statements (simple statements or FOR-block statements) separated by colons. A line тау be used as a 
command. or introduced by a line number as part of a BASIC program Line numbers are whole numbers in 
the range 1 68835 
4! Simple Statements 
411 Declaration 
OPTION BASE 0 Sets the array base globally to 0 
OPTION BASE 1 Sets the base globally to 1 
The default base is 0. 
DIM array name (dimension) 
The dimension mus" be an appropriate numeric expression or a pair of expressions separated by a comma 
Multipie dimensionings separated by commas are allowed. 
Scalars are not expicitly declared. arrays need not be In the latter case a default dimension of Ion 1G 16 
is assumed 


DEF function name (argument) = expression 
declares a user defined function. 
412 Assignment 

LET assignee = expression 
An assignee may be a variable name or an array element. The assignee must be of the type of the evaluated 
expression. The keyword LET may be omitted. 
413 Control 

IF expression THEN line number 

IF expression THEN line 
In the latter case the keyword THEN may usually be omitted. 

GOSUB /ine number 

RETURN (also RET) 

ON expression GOTO line number list 

ON expression GOSUB line number list 

ON ERROR GOTO fine number — Set error trap 

ON BREAK GOTO line number Зе! interrupt trap 

RESUME Resume after trap. 

RESUME /ine number 

GOTO line number 

CONTINUE (also CONT) 

STOP 

RUN 

NEW 

CALL expression, arguments 
This is to call a machine code or other language routine. 
444 Input and Output 

OPEN direction # stream. device, port. parameter string 
Direction is IN or OUT, itis optional and defaults to IN. Stream is an appropnate numeric expression. Device 
and port are numeric expressions which may be omitted. Parameter string is a string expression м 
defaults to null, The information is passed to Ihe operating system which assigns the stream to the device 
and opens il. 


INPUT assignee list INPUT # stream, assignee list. 
INPUT (prompt) assignee list 
The prompt string expression is used to substitute for the default "2" prompt when the stream is the default 
(console) stream. 
PRINT print list. PRINT # stream, print list 
? is a synonym for PRINT. Print list is a sequence of print items and print separators. Print items must be 
separated by at least one print separator, and can be 
expression 
numeric valued expression [formatter] 
TAB (numeric valued expression) 
The formatter controls the numeric output format as in STRS. 
TAB moves the printhead position on the console 
Separators are commas and semicolons, these also contro! the position of the printhead. 
LINPUT assignee LINPUT # stream, assignee 
LINPUT (prompt) assignee 
assign all input until the next NEWLINE (code 13) character from the input stream to the assignee string. 
GET assignee list GET # stream, asignee list 
assign input bytes sequentially to the assignees, string assignees being sel to single character strings, 
numeric assignees to numbers in the range 0. 255. 
PUT expression list PUT stream, expression list 


‘output bytes. If an expression evaluates toa s I the byte corresponding to its first character is used, if the 
‘expression evaluates to а number then this must be in the range 0. 255. 


CLOSE # stream closes the stream. 
LIST range LIST # stream, range 
These output the current program as text. 
Range can be absent or 
line number ine number line number 
-йіпе number line number- 
SAVE # stream outputs the program in "enlokened" form. 


declared equal 10 an expression іп а DEF statement 


226 Unary Operations These all take numeric arguments and yield numeric results 
] unary plus and minus 


NOT The bitwise Boolean operation 

227 Binary Operations with Numeric Arguments which Yield Numeric Results 

+ a Plus minus times divide 

1 Raise to a power 

< <= - Relational operators 

> >= <> {less man less than or equa! equal, greater than. greater than or equal. not equal) 

AND OR The bitwise Boolean operations 

228 Binary Operations with String Arguments which Yield Numeric Results 

< ke m Relational operators returning Boolean results as in the numeric case. 

> >= <> Characters are ordered according to the NewBrain internat codes (which ordening 
agrees with ASCII and hence with alphabelic order) and strings are ordered by first 
difference. 

229 Binary Operations with Stang Arguments which Yield Stnng Results 

+ (аво &) Concatenation 


23 Expression Evaluation 


Within an expression atomic expressions and expressions in parentheses are evatuated hirst Operations аге 
evaluated in the order 


+ - (unary operations) 
AR) 

* = % (binary operations) 

9 »- <> 

AND 

оя Ой having the least binding power 


Mathematical operations and functions are evaluated by the mathematics package. The mathematics 
package has been specially designed to minimise cumulative rounding errors and maintain stability ип 
recursive and iterative calculation. and to obtain maximai computation speed consistent with ten signilicant 
ligure accuracy and long term stability, 


3 INPUT/OUTPUT 

This is perlormed by the NewBrain operating system 
31 Мо Devic 
V/O devices are signilied by whole numbers in the range 0 10 255. In practice in a program. devices are 
usually named as numeric variables whose values signify the device. All input/output peripherals are 
configured by their device drivers as byte serial devices 

32 Data Streams 


Data streams are signified by whole numbers in the range 0 to 255. though in practice numenc variable 
names are used. In BASIC. affer opening a device on a datastream. all communication with that device is via. 
the datastream. When appropriate devices and device divers are connected. appropriate control 
datastreams can be used 10 implement all current / modes including random access. 


4 BASIC STATEMENTS, BLOCKS AND PROGRAMS 

A BASIC statement generally consists ot a keyword followed by certain arguments. А BASIC line consists ol 
Statements (simple statements or f Of. boch statements) separated by colons. A line may be used as a 
Command. or introduced by a line number as part of a BASIC program. Line numbers are whole numbers in 
the range 1 65835 

41 Simple Statements 

41.1 Declaration 


OPTION BASE O Sets the array base globally to 0 
OPTION BASE 1 Sets the base globally to ! 
The delault base is 0 
DIM array name idimension) 
The dimension тив" be an appropriate numeric expression or a pair о! expressions se 
Multipie dimensiorings separated by commas are alowed. 
Scalars are not explicitly declared. arrays need not be in the latter case a default cim ens un ot. iet iti 1 
15 assumed 


arated by а comma 


DEF function name (argument)= expression 
declares a user defined function. 
412 Assignment 

LET assignee = expression 
An assignee may be a variable name or an array element The assignee must be of the type o! the evaluated 
expression. The keyword LET may be omitted. 
413 Contro! 

IF expression THEN ine number 

IF expression THEN line. 
in the latter case the keyword THEN may usually be omitted 

GOSUB line number 

RETURN (азо RET) 

ON expression GOTO line number list. 

ON expression GOSUB line number list 

ON ERROR GOTO line number dei error trap 

ON BREAK GOTO line number Зе! interrupt trap 

RESUME Resume after trap 

RESUME line number 

GOTO line number 

CONTINUE (also CONT) 

STOP 

RUN 

NEW 

CALL expression, arguments 
This is to call a machine code or other language routine. 
414 Input and Output 

OPEN direction # stream, device, port. parameter string 
Direction is IN ог OUT. itis optional and defaults to IN. Stream is an appropriate numeric expression. Device 
and port are numeric expressions which тау be omitted. Parameter string is a string expression which 
delauls to nul. The information is passed to the operaing system which assigns the ream to the device 
and opens it. 


INPUT assignee list INPUT # stream, assignee list 
INPUT (prompt) assignee list 

The prompt string expression is used to substitute for the default 

(console) stream. 


prompt when the stream is the default 


PRINT print list PRINT 4 stream, print list. 
? is a synonym for PRINT. Print list is a sequence о! print items and print separators. Print items must be 
separated by at least one print separator, and can be 
expression 
numeric valued expression |formatter| 
TAB inumeric valued expression) 
The formatter controls the numeric output format as in STRS. 
TAB moves the printhead position on the console 
Separators are commas and semicolons, these also control the position of the printhead. 
LINPUT assignee LINPUT # stream, assignee 
LINPUT (prompt) assignee 
assign all input until the next NEWLINE (code 13) character from the input stream to the assignee string. 
GET assignee #5! GET # stream, asignee list 
assign input bytes sequentially to the assignees, string assignees being sel to single character strings, 
numeric assignees to numbers in the range C. 285 
PUT expression list PUT stream, expression list. 
output bytes. If an expression evaluates toa su J the byte corresponding to its first character is used, if the 
expression evaluates to a number then this must be in the range C. 258. 
CLOSE # stream closes the stream. 
UST range LIST # stream, range 
These output the current program as text. 
Range can be absent or 
ine number—tine number line number 
—line number line number 
SAVE # stream outputs the program in "entokened" form. 


LOAD # stream MERGE # stream VERIFY # stream 


LOAD inputs a new current program in textual or in "entokened" form. MERGE merges the input program 
with the current one. VERIFY checks the current program against the one on the input stream 

LOAD filename MERGE filename 

SAVE filename VERIFY filename 
LOAD filename 15 equivalent to 

OPEN IN # 128, default backup store device, filename 


LOAD # 128 
CLOSE # 128 
and similarly tor others. The filename may be omitted. 
READ assignee list DATA constant list 
RESTORE RESTORE line number 


These last four statements are for the "interna! reader 
415 Miscellaneous. 
POKE expression, expression 
несту addresses machine store. 
RANDOMIZE 
sets the random number generator to an unknown value. 
REM introduces a comment 
REPORT 
if an ON ERROR or ON BREAK trap is set outputs the message which would have been output had it not 
been and halls program or command execution. 
CLEAR CLEAR list 
release store used by all, or selected, arrays variables and constants. 
DELETE range release store used by current program 
RESERVE expression 
reserves {ree store previously available to BASIC to release for use by users machine code or other 
purposes. Statements containing no characters а! all are also allowed. 
42 Blocks 
Blocks are sequences о! simple statements which may or may no! make up program lines, or FOR-blocks 
ich are 
for-statement blocks next-statement 
for-statement із 
FOR variable = initial value TO limit STEP increment 
initial value, limit and increment are numenc valued expressions. 
STEP increment may be omitted. 
next-statement is 
NEXT variable 
The control variable must be numeric and the same in both the for and in the next statement 
43 Programs 
А program is both a sequence о! lines and a sequence о! blocks. An ЕМО statement should be present. 


5 MODE OF OPERATION 

Acertain input/output device. called the console, is open when BASIC is started up. Input from this device is 
treated by BASIC either as lines which are commands 10 be obeyed immediately, or as lines with line 
numbers which are added to the current program to be obeyed later when the program is run. Reserved 
words in lines are "entokened" in the program in order to minimise store usage. When a command or block is 
‘obeyed itis first "compiled" into NewBrain BASIC “object code" (this compilation includes the setting up of 
appropriate datastructures) and then the "object code" is “executed”. When a program is being run the 
Object code is kept and so once obeyed a command can be obeyed again without having to be compiled 
again. This mode о! operation saves time and optimises the performance of programs. 

Despite BASIC being a dynamic compiler, all interactive features are present. While an ON BREAK trap is 
по! set the user can normally break into a program by using the STOP key, inspect and alter values and 
program lines and then CONTINUE execution with ali other states preserved. 


6 NOTES 


{a) Spaces 
Spaces are insignificant in almost all places in NewBrain BASIC. 


(b) Character Set 

NewBrain BASIC allows the user a set of 256 distinct characters. It is assumed thal the character set 
includes the ASCII characters (though it need not include all ot them). BASIC distinguishes between upper 
and lower case alphabetic characters only within string constants and REMark strings. The NewBrain 
keyboard character sel includes all the ASCII characters. viewdala graphics characters and others as well. 
(с) Errors 

NewBrain BASIC produces over 50 numerically coded error messages to aid debugging. 

(9) The depth о! nesting ol for-blocks. GOSUBs. parentheses etc. is limited only by the total amount о! 
memory available. 

(е) Extension. 

The NewBrain operating system contains an extension mechanism comparabie to, but more advanced than 
simple “trapping”. This makes NewBrain "ROM software" real software. not just "Irmware". Programs in 
RAM or ROM can replace or extend programs already present in ROM In particular additional features сап 
be added to NewBrain BASIC without having 10 replace the original ROMs The NewBrain paged memory 
system enables such extension to be virtually indefinite. 
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Тһе NewBrain graphics package 

The NewBrain microcomputer has a comprehensive graphics package, which allows the user to draw 
pictures in high resolution on a TV or monitor display screen. The size of the high resolution area can бе 
selected by the user from BASIC, and the graphics package provides many special features including the 
ability to choose the scale of this area. The graphics package is implemented as a type of device driver, so 
that the user can open one or more graphics streams at any time. 

Facilities available 


The following facilities allow the user Io draw lines on the screen, using an imaginary pen. 


MOVE (xy) Moves the pen to (xy) drawing as il goes, and sets the pen angle to the direction taken. 
MOVEBY (d) Moves the pen a distance d in the direction of the pen angle, drawing as it goes. 
DRAW (xy.c) Draws a straight line to the position (ху) using colour c. 
DRAWBY (d.c) Draws a straight tine of length d in tne direction of the pen angle, using colour c. 
The DRAW and DRAWBY commands do not change the pen position or angle. 
ARC (4,8) Draws a series of short straight lines to approximate a circular arc of length d, turning 
through an angle 8. 
PLACE (ху) Moves the pen to position (xy) without drawing. 
TURN (0) Turns the pen angle to 9 
TURNBY (9) Increases the pen angle by б 
RADIANS Causes angles lo be input or output in radians. 
DEGREES Causes angles to be input or output in degrees. 
BACKGROUND(b) Sets the background colour to b: 
то! 
1 =on 
WIPE Sets the entire display area to the background colour. 
^ DOT (кус) Plots а single dot in colour c at position (ху). 
AXES (a.b) Draws axes crossing at the current pen position. Marks the X-axis al spacing of a and 
the Y-axis а! spacing of b. И either parameter is zero, thal axis is not marked. 
COLOUR (с) Sets the pen colour 


The pen colour тау be 0-3 

No action when drawing 

Lines are drawn in the colour (black or white) opposi 

Lines are drawn in the same colour as the background 

Each point on the screen is changed from white to black or from black to white as the 

line passes through и. 

Ап area о! the screen may be marked off by lines or arcs, and then coloured in 

FILL Colours the current position according to the current pen colour, then lilis the 
‘surrounding area up to an enclosing boundary formed by lines whose resultant 
colour is the same and by the edges of the screen 

The local screen scale may be changed, and tne position of the centre selected 


lo the background colour 


өм-о 


RANGE (a.b) Sets the coordinate scale so that the width of the screen is a and its height is b. 
CENTRE (ab) Sets the origin of the coordinates relative to Ine bottom left comer о! dispiay area. 
Text strings may be plotted in the high-resolution area, and the mode in which this is done may be selected: 
MODE im) Sets the mode parameter (only relevant to plotting texi strings at present) 


Using the graphics гот BASIC 
The graphics commands listed above аге used by entering PLOT followed by one or more of the items in the 
list, separated by commas. 
Eg. PLOT PLACE (166), MOVE (16,46), MOVE (80.46), MOVE (16.46) 
The PLOT statement may contain a string or a number, which will be plotted starting at the pen position. 
Eg. the result R of a computation might be shown at the bottom of the screen with PLOT 
RANGE (110,100). PLACE (10,0), “RESULT =", PLACE (380). R 
Another facility - the PEN function - can be used in a BASIC print or assignment statement. Itallows the user 
= to ascertain the location of the pen on the screen, and certain other йет. 
Eg PRINT PEN (0). PEN (1): REM position 
PW= PEN (9) 
The values which can be accessed via the PEN function аге 
0 x- coordinate of pen 
7 Y-coordinate o! pen 


pen angie 
pen colour 
background colour 
mode 
colour о! point at current pen position 
address of first memory location in the high-resolution display 
address of last memory location in the high-resolution display. plus 1 
width of the display (in pixels} 
А graphics stream is set up using OPEN to open a stream of type 11. This will normally share the memory 
area of the console stream, stream zero. As a high resolution display occupies more memory than а 
character screen display, the shared area needs to be rather large. 
eg. OPEN # 00,7170" 
OPEN # 1.11 
А graphics stream need not share the memory of the console stream if another stream is available with а 
sufficiently large screen area. 
eg. OPEN # 601, "170" 

OPEN # 1,11,-#6" 
The height o! the graphics area required is given in the OPEN statement For 200 graphics rows, which 
occupy the same display area in the TV or monitor as 20 rows о! characters, OPEN # 1,11, "200" or 
OPEN % 1.11. 46200" is used. The OPEN statement may also be used to select the width. 
The graphics area may occupy the tull width ofthe screen or a narrower part thereof. The selection is made by 
adding “W” or “М” in the parameter string before the height, 

eg. OPEN #1,11,"W200" or OPEN # 1,11, "#6, W200" lor a wide screen, 

OPEN ж 1.11 "N200" or OPEN # 1.11, "#6, N200" for a narrower 

screen, 
The Operating System remembers the first graphics stream opened, and this is used by BASIC for each 
PLOT statement or PEN function. If more than one graphics stream is opened, PLOT statements may be 
directed to one or the other by adding the stream number, as for PUT or PRINT: 

PLOT # 1, "GRAPHICS STREAM 1” 
The pen tunction may also be used with а stream number to get information trom each graphics stream, as 
for example 


о-и шт 


PRINT PEN (6 3, 0), PEN (# 3.1) 
to print the Х and Ү coordinates of the pen position belonging to stream 3. 


Technical details 

1 OPEN 

The parameter string gives the linked stream, the width option, and the height selected for the graphics 
stream. 

Linked stream is “# integer" or null and defaults to 0, ie. the console device, and determines the stream 
whose display area is to be shared. The selecied stream must be a screen device, whose height is sufficient 
to accommodate the requested height. Graphics lines require up to ten times as much memory as the 
character lines they replace 
Width option is “W” or “N” (default is "W"), and determines whether the tull width of the screen or a narrower 
part of it is to be used. Selecting "N" reduces the memory requirement by 20%. 

Height is “integer” (or "integer" if the width option is omitted), and determines the number of graphics lines 
‘on the page. The default is 150. The maximum height is 229 if a wide screen is selected anc 230 for a 
narrower screen. 


2 Memory Required 

The linked stream must be a screen-type stream, opened in advance and of a large enough size to 
accommodate the desired graphics area To provide a graphics stream with width option “w” and height 
150-159, an original screen size of 110 is required. An original screen size of 114 would provide some extra 
memory to enable the FILL command to be used more effectively. For each extra 10 lines of graphics height, 
the original screen size should be increased by 6 lines. 

When the width option is "n", an original screen size of 86 is required to provide a graphics stream with 
height 141-150. An origina! screen size of 90 would provide some extra memory to enable the FILL 
command to be used more effectively. For each extra 10 lines of graphics height, the original screen size 
should be increased by 5 lines. 


3 Initial Values 

When a graphics stream is opened. the following initial values are set up: 
X-Range 1 

Y-Range 1 


Origin. Bottom left-hand comer 


Pen position (0.0) 
Pen angie 9 
Angles in Radians 
Background 0 

Pen colour 1 

Mode 0 


4 Text Plotting 
Either a string or an expression may appear in а PLOT statement: an expression is first converted to a string, 
аз by STRS, and will always appear with a leading and trailing space. Each character is plotted in turn, ina 
matrix ol 8 x 10 pixels. with the lower left corner of the hrst character al the current pen position. Each ofthe 80 
pixels in the matrix is coloured, using the pattern of the character as a chart for this operation. If the point in 
the character pattern is part of the surround the corresponding point of the screen is plotted using the 
MODE value 0. 1, 2 or3 If the point in the character pattern is part of the character itself, Ihe corresponding 
point on the screen is plotted using the COLOUR value 0. 1. 2 or 3. So the stalement 

PLOT COLOUR (2), MODE (1), "NewBrain 
produces the text "NewBrain" on a reversed-tield, and 

PLOT COLOUR (1), MODE (2). "NewBrain* 
produces the text "NewBrain" іп normal colouring, and clears blank space around the text. A Page zero 
location is used to hold the address o! the 256 character charts, o allow user definable characters in the 
high resolution area. 
5 Default Graphics Stream Number 
Each time a graphics stream is opened. ils own stream number is inserted into the Page Zero location 
"delault graphics stream number" if and only if that location contained the value zero Each lime a graphics 
stream is closed, the contents of the “default graphics stream number” location are se! to zero if and only if 
that location contained the number of the closing stream. This ensures that if a user only has one graphics. 
‘stream open а! a time. the PLOT and PEN statements will atways refer to that stream. 
6 Graphics Control Strings 
Тһе PLOT and PEN commands enable a graphics stream to be controlled directly тот BASIC in a straight- 
forward fashion. Each PLOT item, other than a tex! string. 8 coded by BASIC as a sequence of [rom two to 
twenty bytes and output to the driver. which then interprets this sequence and Carries out the instruction, 
The command sequence is as follows. 


First byte value 16 

Second byte plot command number 

Bytes 3108 first parameter, if required 
Bytes 9 to 14 second parameter. if required 
Bytes 15 to 20: third parameter. il required. 


Each parameter is а sh.. bye floating point number, output low byte lust The command numbers, and 
expected number о! parameters, are as follows: 


0  MOVE(2 10 RANGE (2) 

1 TURN (1) 1! CENTRE (2) 

2 АВС (2) 12 МОУЕВҮ (1) 

3 TURNBY (1) 12 DRAW (3) 

4 = MODE (1) 14 DRAWBY (2) 

5 FILL (none) 15 BACKGROUND (1) 

6 COLOUR) 16 WIPE (попе) 

7 reserved for text strings 17 AXES (2) 

used to output PEN 18 PLACE (2) 
parameter (1) 19 RADIANS (попе) 

9 00т(3) 20 DEGREES (попе) 

For a text string, the command sequence is: 

First byte 16 

Second byte: 7 

Third byte number of characters n 

Fourth byte 0 

Bytes 5 0 4+п test 


Alter command 8 is output with its parameter, six bytes may be input trom the stream which will make up the 
floating-point value of the selected PEN function 

All these control sequences are transparent to the user. as BASIC always constructs the necessary 
sequences from the PLOT commands. 
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Screen Editor - Technical Specification 

General Description 

Тһе NewBrain keyboard-Screen-vt display editor, XIO, is an interactive input/output device for communi- 
cation between a user or operator of the NewBrain and a NewBrain user-program such as BASIC. The 
editor interfaces with the NewBrain input/Output System, IOS. 

Communication between the editor and the program is via the five standard 105 commands, OPENIN, 
OPENOUT, INPUT, OUTPUT and CLOSE Since tne editor is an Input/Output device OPENIN is equivalent 
to OPENOUT. 

The Displays 

The TV/video display editor holds а page о! between 1 and 255 lines of 40 or 80 characters per tine. The 
screen display will show 24 or 30 lines and this window is scrolled up and down the page. (OS allows lor 
multiple copies of a device to be open; thus, memory allowing, up to 255 pages can be simultaneously 
maintained. 

The vt display editor holds a single line between 16 and 254 characters in length. The 16 character vl display 
window is scrolled backwards and forwards over the line. The editor waits for Ihe user to press the NEWLINT. 
key before displaying a new ипе. This wait can be suppressed by outputting the appropriate control codes. 
During the wait the window can be scrolled trom side to side by the cursor contro! keys. 

‘The у! display can also be used as a window on a screen page, displaying the part of the current line around 
the cursor. 

Character Sets 

The vt display character set consists of the 64 ASCI! upper case characters, excepting character 95 tor 
which the £ sign is substituted, and 64 graphics characters. All characters сап be blinked. The v! editor uses. 
only 65 of these characters and reserves blinking as an indication of cursor position. Characters sent tothe 
editor are recorded before display, so that lower case letters are displayed as their upper case equivalents, 
and so the coding agrees with that used for the screen display. 

The screen display character set depends on the character generator ROM fitted. 512 characters аге 
available, though at most 255 characters can be displayed at a time. Character set selection is achieved by 
the "Set TV Mode" (control W) code. in certain modes 127 characters are available for display, іп normal or 
reverse field. According lo mode the background сап also be set to forward or reverse field. Although 32 
codes are used for controls, all 255 dispiayable characters can be used by using the ESCAPE control code. 
The code 0 is used by the hardware for contro! and cannot be displayed. 


'upplied on open are as follows. 
1 Device Number 


9 TVO -video screen editor only 
3 шо “vt single line editor ("line image") 
4 TUO -video screen editor, using v! display as a window on the screen image 


2 Port Number 

No use is made of this by the device. Thus this can be used to make IOS open multiple copies of the device. 
3 Parameter String 

For TVO А TLIO this consists of two optional fields: 


length -A single character s "S". "I" or “L”. S indicates forty character lines, 
L indicates 80 character lines. Default 1s 40. 
depth ~ An integer in the range 1 ..255, being the number of 40 or 80 character 


lines on the page. Default is 24. 
For LIO this is a single optional field, an integer in the range 16.255 being the number of characters in the 
"line mage". 
Note that TVIO and TLIO behave the same way as ШО when the requested depth is 1. 
Input 
Under normal circumstances INPUT causes а line of characters 10 be collected trom the keyboard 
interaction and the first character of the line to be returned. Subsequent INPUT commands will return the rest 
ol the characters of the line in sequence, including the end of line character (NEWLINE, code 13). A further 
Call to INPUT will cause a new line to be collected and returned. Exceptionally a sequence of calls to INPUT 
will return the character al tne cursor position, the line on which the cursor is positioned (without collecting 
а new line by keyboard interaction), the entire current page or the x-y cursor address. 


Keyboard Interaction 

The keyboard interaction is started when а call is made to INPUT when there are not already characters set 
to be returned by the editor. The interaction continues until the NEWLINE key is pressed. The cursor is 
always displayed during the interaction. If the interaction starts with the cursor at the start of a line all control 
codes are available through the keyboard апа have the same effect as il OUTPUT. if the interaction starts 
with the cursor within a line, backspacing past that position. and codes which move the cursor out of Ihe line. 
on which it is resting are suppressed. The part of Ihe line up to the cursor position when the interaction was 
started (the "prompt") is not returned by INPUT. The special contro! keys on the keyboard and the main keys 
used with the CONTROL key generate control codes. Normally the main keys generate lower case letters, in 
Conjunction with SHIFT upper case letters, in conjunction with GRAPHICS codes in the range 128-255 
(‘graphics codes”). Keys 0..9 in conjunction with CONTROL change the "keyboard mode ie. the 
correspondence between the key pressed and the code generated; but these keys do nol themselves 
produce a character code. Contro! and ! enters “SHIFT Lock", CONTROL and returns the keyboard mode 
to normal. 

Output 

Calls to output cause a character lo be pu! onto the screen or М! display. Thirty-two characters are used as 
control codes, accessing special features ol the editor. The effect of contro! codes other than NEWLINE із 
the same whether entered via OUTPUT or entered via the keyboard interaction in response toa callto INPUT, 
when the cursor is at the beginning of a ine. 

Screen Lines, Cursor Display, Autodelete Feature 

Lines on the screen may be of any engl up to the size ol page. Lines longer than 40 or 80 characters wrap 
round, a continuation character being displayed at the start of each screen line other than the first to indicate. 
wat this is a continuation line. The cursor is displayed as a blinking underline or a blinking block. The latter 
mode о! display is used for two purposes. When the cursor is beyond the right end of the line - ie. the next 
character entered will be the first character of a subsequent continuation, itis displayed at the right most 
position in the line as a block. This contrasts with being displayed in the right-most position as an underline 
when the next character entered is to be entered at that position. The other use of the block cursor is at the 
left-most position of a line just after a NEWLINE has been entered. This indicates that if the next character to 
be entered is not a control code the present contents of the line will be cleared to spaces. This "autodelele" 
feature enables a page to be overprinted without having to clear outdated information. The autodelete mode 
is cancelled if the first character entered is a control code, so that overprinting of forms etc, where information 
previously printed is to be retained, can be achieved. 

Use as BASIC Console 

BASIC opens an editor device on Stream 0 when started up. The parameters used lor this depend on the 
hardware. For a NewBrain D. MDB ШО with a length of 80 is used, for А от AD TVIO with a length of 40 and 
depth of 24, for М, МО TVIO with a length of 80 and depth 24. Port number 0 is used 


Control Codes 


Hex Decimal Control кеу 

0 0 @ Null 

1 1 A Sh/insert. Insert line 

2 2 8 Shi 

3 3 © Cnti/newiine Send page 

4 4 5 End of file 

5 5 E Send line 

6 6 F Show cursor 

7 7 © Cursor off 

8 8 H - Cursor left 

9 9 Й Cntl/escape Tab 8 spaces 

A 10 J П Cursor down 

в 11 к 1 Cursor up 

с 12 * Home Cursor home 

D 13 M Newine Newine 

E 14 N SO» Attribute on 

F 15 9 Sh/escape Attribute ой 

10 16 P Graphics escape 
11 17 о Insert Enter insert mode 
12 18 R Grph/t Make new line 

13 19 5 Grph/i Make continuation line 
14 20 T Grph/newline Send cursor character 
15 * u Groh/insert Sendx y 

16 22 у Cnt/insert Set cursor x, y 

17 23 w Grph/escape Set TV control 
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Screen Editor- Technical Specification 

General Description 

The NewBrain keyboard-Screen-vt display editor, XIO. is an interactive input/output device for communi- 
cation between a user or operator of the NewBrain and a NewBrain user-program such as BASIC. The 
editor interfaces with the NewBrain Input/Output System, IOS. 

Communication between the editor and the program is via Ihe five standard 105 commands, OPENIN, 
OPENOUT, INPUT, OUTPUT and CLOSE. Since the editor is an Input/Output device OPENIN is equivalent 
10 OPENOUT. 

The Displays 

The TV/video display editor holds a page of between 1 and 255 lines of 40 or 80 characters per ипе The 
screen display will show 24 or 30 lines and this window is scrolled up and down the page. IOS allows for 
multiple copies of a device lo be open: thus, memory allowing, up 10 255 pages can be simultaneously 
maintained. 

The v! display editor holds a single line between 16 and 254 characters in length. The 16 character vl display 
window is scrolled backwards and forwards over the line. The editor wails forthe user to press the NEWLI^ С 
key belore displaying a new line. This wait can be suppressed by outputting the appropriate control codes. 
During the май the window can be scrolled trom side to side by the cursor control keys. 

‘The vi display can also be used as a window on a screen page, displaying the part of the current line around 
the cursor. 

Character Sets 

The v! display character set consists of the 64 ASCI! upper case characters, excepting character 95 tor 
which the £ sign is substituted, and 64 graphics characters. All characters can be blinked. The v editor uses 
only 65 of these characters and reserves blinking as an indication of cursor position. Characters sent tothe 
editor are recorded before display, so that lower case tellers are displayed as their upper case equivalents. 
and so the coding agrees with that used lor the screen display. 

Tne screen display character set depends on the character generator ROM fitted. 512 characters are 
available, though at most 255 characters can be displayed at a time. Character set selection is achieved by 
the "Set TV Mode" (control W) code. in certain modes 127 characters are available for display, іп normal or 
reverse field. According lo mode the background can also be set to forward or reverse field. Although 32 
codes are used for controls, all 255 displayable characters can be used by using the ESCAPE control code. 
The code 0 is used by the hardware for contro! and cannot be displayed 

Open 

Parameters supplied on open are as follows: 

1 Device Number 


0 WiO - video screen editor only 
3 шо "М single line editor ("line image") 
4 TUO -video screen editor, using v! display as a window on the screen image 


2 Port Number 

No use is made of this by the device. Thus this can be used to make IOS open multiple copies of the device. 
3 Parameter String 

For ТМО А TLIO this consists of two optional fields 


length - А single character “5”, S =I" or "L'. S indicates forty character lines, 
L indicates 80 character lines. Default is 40. 
depth an integer in the range 1 .. 255, being the number of 40 or 80 character 


lines on the page. Default is 24 

For tuo this is a single optional field, an integer in the range 16.. 255 being the number of characters in the 
"line image". 

Note that ТУЮ and TLIO behave the same way as ШО when the requested depth is 1 

Input 

Under normal circumstances INPUT causes a line of characters to be collected from the keyboard 
interaction and the first character of the line to be returned. Subsequent INPUT commands will return the rest 
of the characters of the line in sequence. including the end of line character (NEWLINE, code 13). A further 
call to INPUT will cause a new line to be collected and returned. Exceptionally a sequence of calis to INPUT 
will return the character al the cursor position. the line on which the cursor is positioned (without collecting 
а new line by keyboard interaction), the entire current page or the x-y cursor address 


Keyboard Interaction 

The keyboard interaction is started when a call is made to INPUT when there are not already characters set 
io be returned by the editor. The interaction continues unti! the NEWLINE key is pressed. The cursor is 
always displayed during the interaction. ifthe interaction starts with the cursor at the start of a line ай control. 
codes are available through the keyboard and have the same effect as il OUTPUT. if tne interaction starts 
with the cursor within a line, backspacing past that position and codes which move the cursor out of the line 
оп which itis resting are suppressed. The part of the line up to the cursor position when the interaction was 
started (the "prompt") is not returned by INPUT. The special contro! keys on the keyboard and the main keys. 
used with the CONTROL key generate control codes. Normally the main keys generale lower case letters, in 
conjunction with SHIFT upper case letters, in conjunction with GRAPHICS codes in Ihe range 128-255 
(‘graphics codes") Keys 0..9 in conjunction with CONTROL change the "keyboard mode" - ie. the 
‘correspondence between the key pressed and the code generated; bul these keys do not themselves 
produce a character code. Control and 1 enters “SHIFT Lock", CONTROL and О returns the keyboard mode 
10 normal. 

Output 

Calls to output cause a character to be put onto the screen or v! display. Thirty-two characters are used as 
Control codes, accessing special features of the editor. The effect of control codes other than NEWLINE is 
the same whether entered via OUTPUT or entered via the keyboard interaction in response to a call to INPUT, 
when the cursor is at the beginning of a line. 

Screen Lines, Cursor Display, Autodelete Feature 

Lines on the screen may be of any length up to the size of page. Lines longer than 40 or 80 characters wrap 
round, a continuation character being displayed atthe start of each screen line other than the lirstlo indicate. 
that this is a continuation The cursor is displayed as a blinking underline or a blinking block. The latter 
mode of display is used for two purposes. When the cursor is beyond the right end of the line - ie. the next 
character entered will be the first character о! a subsequent continuation, s displayed al the rightmost 
position in the line as a block. This contrasts with being displayed in the right-most position as an underline 
when the next character entered is to be entered al that position. The other use of the block cursor is al the 
left-most position of a line just after а NEWLINE has been entered. This indicates that ifthe next character lo 
be entered is not a control code the present contents of the line will be cleared 10 spaces. This “autodelete” 
feature enables a page to be overprinted without having lo clear ouldaled information. The autodelete mode 
is cancelled it the first character entered is a control code, so that overprinting of forms etc, where information 
Previously printed is to be retained, can be achieved. 

Use as BASIC Console 

BASIC opens an editor device on Stream 0 when started up. The parameters used for this depend on the 
hardware, For a NewBrain D, MDB LIIO with a length of 80 is used, for A or AD TVIO with a length of 40 and 
depth of 24, for M, MD TVIO with a length of 80 and depth 24, Port number 0 is used. 


Control Codes 


Hex Decimal Control Key 

0 0 ө ми! 

1 1 А Sh/insert Insert line 

2 2 в 5м 

3 3 с Cnt//newline Send page 

1 4 5 End of file 

5 5 Е Send line 

6 6 F Show cursor 

7 f G Cursor off 

8 8 H - Cursor lett 

9 9 i Спшеѕсаре Tab 8 spaces 

A 10 J n Cursor down 

B 11 к 1 Cursor ир 

с 12 5 Home Cursor home 

D 13 м Меміпе Newline 

Е 14 N shyt Attribute оп 

F 15 o Sh/escape Attribute off 

10 16 Р Graphics escape 
11 17 о Insert Enter insert mode 
12 18 R бгр Make new line 

13 19 5 Grph/i Make continuation line 
14 20 T Groh/newine Send cursor character 
15 2 у Grpn/insert Send x y 

16 22 у Спбпзеп. Set cursor x, y 

17 23 w Grph/escape Set TV control 


86 


-05 


22 


23 


24 x Sw- Delete let 
25 Y 5һ/— Delete character 

26 2 - Cursor right 

27 í Escape Escape next character 
28 / Сп Cursor home left 

29 1 Саш Cursor home right 

30 1 Cu /home Clear line 

31 Shift/home Clear page 


Interpretation of Control Codes 


No action. 
A line ol spaces is inserted at the cursor, the cursor line and subsequent ines are shifted down. The 
last line is lost 
The whole cursor line including the lines of which itis a continuation it any) and any continuations of itis 
deleted. Subsequent lines are shifted up, sufficient lines of spaces being inserted at the end 
‘Subsequent calls to INPUT will return all the characters on the page, including NEWLINES. This mode 
is cancelled when all characters are returned, or by a cal! to OUTPUT. After returning all characters the 
Cursor will be in the top left "home position” on the screen. 
No action (this code тав a special meaning in BASIC). 
‘Subsequent calls to INPUT will return all the characters of the current line, including the NEWLINE 
Cancelied as code 3. 
The cursor will be displayed at al! times until code 7 is entered. 
The cursor wili not be displayed, except during keyboard interaction, until code 6 is entered. 
Move cursor left one space. This is not possible if at the top left-most position on a line. 
Move cursor right at least one space and sufficiently many spaces 10 bring it to а screen column а 
multiple of 8 spaces from the start, or failing that, to the start of the next line or to the space ater the 
continuation character on the next line. 
Move cursor vertically down one space. This is not possible if on the bottom line of the screen, 
Move cursor vertically up one space. This is not possible if on the top line of the screen. 
Home cursor to top len of screen. 
Move cursor to the start of the next line. In INPUT end keyboard interaction. On the bottom line scroll 
screen up losing lop line. 
Invert the top bit of all subsequent non-contro! codes belore displaying. Subsequent characters 

2.127 willbecome 160... 255,129..256 will become display codes ! .. 127 (128 become O which 
is not displayable and is always treated as a NULL control code). This mode is cancelled only when 
code 15 is entered. 
Cancel mode introduced by code 14. 
No action - this code is reserved for use by a high resolution display editor. 
Subsequent characters will be inserted at the cursor position, characters to the right on the line being 
scrolled right and, when appropriate, down (causing subsequent lines to be scrolled down and the 
bottom tine lost). the line already fills the “line mage (LIIO) or the screen page (TVIO or TLIO) this is not 
possible. This mode is cancelled when any control code is entered. 
The current screen line, if it is a continuation line, is made the start of a new line. Continuations of il are 
scrolled back and up if required. 
The current screen line is made a continuation of the line above it. Subsequent continuations of it are 
scrolled down and right if necessary. 
Asubsequent call to INPUT will return the character 
same way as code 3. 
Two subsequent calis to INPUT will return the “x-y cursor address", firstly the x address which is the 
horizontal displacement of the cursor trom the left of the screen starting at . then the у address which is 
the vertical displacement from the top of the screen, starting at 1 (irrelevant in the case of ШО), 
Cancelled as code 3. 
The two bytes next entered are interpreted as an x-y cursor address (see code 21), and the cursoris setto 
the given position. This mode is cancelled when the two bytes have been received by the editor, or if a 
call to INPUT intervenes. 
Set TV control, certain bits of the next byte entered are loaded into the video hardware "TV control 
register". The bits are currently used as follows 
bit 
3 1-8 lines/character, upper Character ROM set 

0 = 10 lines/characler, lower Character ROM set 

Il character set 


me cursor position. This mode is cancelled in ine 


11 


24 


25 
26 
27 


28 
29 
30 


ЕП 


0 = half character sel, top bit used to reverse character field 
0 1 = black background 
O= white 
This mode is cancelled in the same way аз code 22. 
Delete the character to the left of the cursor moving the cursor left one space. This has no effect iat the 
start of a line (not a continuation line) or if Ihe character is outside the LIO window. The rest of the line to 
the right of the cursor is scrolled to the left. and it and subsequent lines up if necessary. 
Delete the character а! the cursor. Otherwise as code 24. 
Move cursor right one space. this is not possible if at the end of a line. 
Put the next character directly into the display- ie. do not trea! it as a control code. This mode is 
cancelled after the next character has been entered. or if a call to INPUT intervenes, 
Send cursor to the lo most position on this line. 
Send cursor to the right-most position on this line. 


Replace the current ine by a line of spaces, scrolling up subsequent lines if appropriate. Send cursor to 
beginning of line. 


Clear the whole screen to spaces and send cursor to “поте” top lett. 


